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Introduction 


The Microsoft® C Run-Time Library is a set of over 500 ready-to-use functions 
and macros designed for use in C programs. The run-time library makes program- 
ming easier by providing 


u Fast and efficient routines to perform common programming tasks (such as 
string manipulation), sparing you the time and effort needed to write such 
routines 


«= Reliable methods of performing operating-system functions (such as opening 
and closing files) 


The C run-time library is important because it provides basic functions not pro- 
vided by the C language itself. These functions include input and output, memory 
allocation, process control, graphics, and many others. 


This book describes the Microsoft C run-time library routines included with the 
Microsoft Professional Development System version 6.0. These comprise all of 
the routines included with earlier versions of Microsoft C, as well as many new 
routines. 


NOTE Microsoft documentation uses the term “OS/2” to refer to the OS/2 systems— 
Microsoft Operating System/2 (MS@ OS/2) and IBMe 08/2. Similarly, the term “DOS” refers 
to both the MS-DOS@ and IBM Personal Computer DOS operating systems. The name of a 
specific operating system is used when it is necessary to note features that are unique to 
that system. 


About the C Run-Time Library 


The Microsoft C run-time library contains a number of new routines and features 
which support American National Standards Institute (ANSI) C compatibility, 
OS/2 and XENIX® programming, and sophisticated graphics programming. . 


To ease the task of transporting programs from one operating system to another, 
the description of each library routine includes compatibility boxes, which show 
at a glance whether the routine is compatible with ANSI C, MS-DOS, OS/2, 
UNIX®, and XENIX. (In this book, references to XENIX systems also encom- 
pass UNIX and other UNIX-like systems.) 
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ANSI C Compatibility 


The C run-time library routines are designed for compatibility with the ANSI C 

’ standard, which Microsoft C compilers support. The major innovation of ANSI C 
is to permit argument-type lists in function prototypes (declarations). Given the 
information in the function prototype, the compiler can check later references to 
the function to make sure that the references use the correct number and type of 
arguments and the correct return value. 


To take advantage of the compiler’s type-checking ability, the include files that 
accompany the C run-time library have been expanded. In addition to the defini- 
tions and declarations required by library routines, the include files now contain 
function declarations with argument-type lists. Several new include files have 
also been added. The names of these files are chosen to maximize compatibility 
with the ANSI C standard and with XENIX and UNIX names. 


OS/2 and XENIX. Programming 


Microsoft C run-time library routines are designed to maintain maximum com- 
patibility between MS-DOS, OS/2, and XENIX or UNIX systems. The library 
offers a number of operating-system interface routines that allow you to take 
advantage of specific DOS and OS/2 features. 


Most of the functions in the C library for DOS and OS/2 are compatible with like- 
named routines in the C library for XENIX. For additional compatibility, the 
math library functions have been extended to provide exception handling in the 
same manner as the UNIX System V math functions. 


Expanded Graphics Library 


The Microsoft C run-time library now contains over one hundred graphics 
routines. The core of this library consists of several dozen low-level graphics 
routines, which allow your programs to select video modes, set points, draw 
lines, change colors, and draw shapes such as rectangles and ellipses. You can 
display real-valued data, such as floating-point values, within windows of differ- 
ent sizes by using various coordinate systems. 


Recent additions to the graphics library include presentation graphics and 
fonts. The presentation-graphics library provides powerful tools for adding 
presentation-quality graphics to your programs. These routines can display data 
as a variety of graphs, including pie charts, bar and column charts, line graphs, 
and scatter diagrams. — 
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The fonts library allows your programs to display various styles and sizes of text 
in graphics images or charts. You can use font-manipulation routines with any 
graphics routines that display text, including presentation graphics. 


About This Book 


This book assumes that you understand the C language and know how to compile 
and link programs. If you have questions about these subjects, consult your com- 
piler documentation. 


This book has two parts. Part 1, “Overview,” introduces the Microsoft C library. 
It describes general rules for using the library and summarizes the main catego- 
ries of library routines. Part 1 contains the following chapters: 


Chapter 1, “Using C Library Routines,” gives general rules for understanding 
and using C library routines and mentions special considerations that apply to 
certain routines. It is recommended that you read this chapter before using the 
run-time library; you may also want to turn to Chapter 1 when you have ques- 
tions about library procedures. 


Chapter 2, “Run-Time Routines by Category,” lists the C library routines by 
category and discusses considerations that apply to each category. This chap- 
ter makes it easy to locate routines by task. Once you find the routine you 
want, turn to the reference page in Part 2 for a detailed description. 


Chapter 3, “Global Variables and Standard Types,” describes variables and 
types that are used by library routines. Global variables and standard types 
are also described in the reference descriptions of the routines that use them. 


Part 2, “Run-Time Functions,” describes the library routines in alphabetical 
order. Once you are familiar with the C library rules and procedures, you will 
probably use this part most often. 


Other Books of Interest 


This book provides a guide to the C run-time library provided with ne Microsoft 
C Professional Development System version 6.0. 
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The following books cover a variety of topics that you may find useful. They are 
listed only for your convenience. With the exception of its own publications, 
Microsoft does not endorse these books or recommend them over others on the 
same subject. 


Barkakati, Nabajyoti. The Waite Group’s Microsoft C Bible. Indianapolis, IN: 
Howard W. Sams, 1988. 


A topical guide to the Microsoft C run-time library. A similar volume is avail- 
able for the Microsoft QuickC® product. 


Campbell, Joe. C Programmer’ s Guide to Serial Communications. Indi- 
anapolis, IN: Howard W. Sams & Company, 1987. | 


A comprehensive guide to the specialized area of serial communication pro- 
gramming in C. 


Hansen, Augie. Proficient C: The Microsoft Guide to Intermediate & Ad- 
vanced C Programming. Redmond, WA: Microsoft Press, 1987. 


An intermediate-level guide to C programming. 


Harbison, Samuel P., and Guy L. Steele, Jr. C: A Reference Manual, 2d ed. 
Englewood Cliffs, NJ: Prentice Hall, 1987. 


A comprehensive guide to the C language and the standard library. 


Kernighan, Brian W., and Dennis M. Ritchie. The C Programming Language, 
2d ed. Englewood Cliffs, NJ: Prentice Hall, 1988. 


The first edition of this book is the classic definition of the C language. The 
second edition includes new information on the proposed ANSI C standard. 


Lafore, Robert. Microsoft C Programming for the IBM. Indianapolis, IN: 
Howard W. Sams & Company, 1987. 


The first half of this book teaches C. The second half concentrates on specif- 
ics of the PC environment, such as BIOS calls, memory, and video displays. 


Mark Williams Company. ANSI C: A Lexical Guide. Englewood Cliffs, NJ: 
Prentice Hall, 1988. 


A dictionary-style guide to the ANSI C standard. 


Plauger, P. J., and Jim Brodie. Standard C. Redmond, WA: Microsoft Press, 
1989. 


A quick reference guide to the ANSI C implementation by the secretary and 
chairman of the ANSI-authorized C Programming Language Standards 
Committee. 
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a Plum, Thomas. Reliable Data Structures in C. Cardiff, NJ: Plum Hall, 1985. 
An intermediate-level look at data structures using the C language. 
m= Plum, Thomas, and Jim Brodie. Efficient C. Cardiff, NJ: Plum Hall, 1985. 


A guide to techniques for increasing the efficiency of C programs. 


a Press, William H., Brian P. Flannery, Saul A. Teukolsky, and William T. Vet- 
terling. Numerical Recipes in C: The Art of Scientific Computing. New York: 
Cambridge University Press, 1988. 


A comprehensive look at numerical techniques using the C language. 


= Schustack, Steve. Variations in C: Programming Techniques for Developing 
Efficient Professional Applications. Redmond, WA: Microsoft Press, 1985. 


An intermediate-level guide to developing business applications in C. 


m Ward, Robert. Debugging C. Indianapolis, IN: Que Corporation, 1986. 


An advanced guide to the theory and practice of debugging C programs. 


a Wilton, Richard. Programmer’s Guide to PC and PS/2 Video Systems:Maxi- 
mum Video Performance from the EGA, VGA, HGC, & MCGA. Redmond, 
WA: Microsoft Press, 1987. 


An advanced guide to all the PC and PS/2 video modes. 


Document Conventions 


This book uses the following document conventions : 


Example 


STDIO.H 


_far 


expression 


[option] 


Description 


Uppercase letters indicate file names, segment 
names, registers, and terms used at the 
operating-system command level. 


Boldface letters indicate C keywords, operators, 
language-specific characters, and library routines. 
Within discussions of syntax, bold type indicates 
that the text must be entered exactly as shown. 


Words in italics indicate placeholders for informa- 
tion you must supply, such as a file name. Italics are 
also occasionally used for emphasis in the text. 


Items inside double square brackets are optional. 
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#pragma pack {112} Braces and a vertical bar indicate a choice among 
two or more items. You must choose one of these 
items unless double square brackets surround the 


braces. 

#include <io.h> This font is used for examples, user input, program 
output, and error messages in text. 

CL options [files...]] Three dots following an item indicate that more 
items having the same form may appear. 

while() A column of three dots tells you that part of the ex- 

{ ample program has been intentionally omitted. 

} 

CTRL+ENTER Small capital letters are used for the names of keys 


on the keyboard. When you see a plus sign (+) be- 
tween two key names, you should hold down the 
first key while pressing the second. 


The carriage-return key, sometimes marked as a 
bent arrow on the keyboard, is called ENTER. 


“argument” Quotation marks enclose a new term the first time it 
is defined in text. 


"C string" Some C constructs, such as strings, require quotation 
- marks. Quotation marks required by the language 
have the form " "and '' ' rather than “” and’ ’. 


Color Graphics The first time an acronym is used, it is often 
Adapter (CGA) spelled out. 


Special Offer xi 


Special Offer 
Companion Disk for Microsoft C Run-Time Library Reference 


Microsoft Press has created a companion disk for Microsoft C Run-Time Library 
Reference. This disk, available in 5.25- and 3.5-inch format, contains nearly 300 
example programs from the book. You can use code fragments from the compan- 
ion disk for commercial or personal purposes without infringing on the copyright 
of the book. 


Domestic Ordering Information 


To order, use the special reply card bound in the back of the book. If the card has 
already been used, please send $19.95 (plus sales tax if applicable: CA residents, 
5% plus local option tax, CT 8%, FL 6%, IL 5%, KY 5%, MA 5%, MN 6%, MO 
4.425%, NJ 6%, NY 4% plus local option tax, SC 5%, TX 6% plus local option 
tax, WA State 7.8%) and $2.50 per disk set for domestic postage and handling 
charges. Mail your order to: Microsoft Press, Attn: Companion Disk Offer, 
21919 20th Ave SE, Box 3011, Bothell, WA 98041-3011. Please specify 5.25- 
inch format or 3.5-inch format. Payment must be in U.S. funds. You may pay by 
check or money order (payable to Microsoft Press) or by American Express, 
VISA, or MasterCard. (If paying by credit card, please include both your card 
number and the expiration date.) Allow 2—3 weeks for delivery. 


Foreign Ordering Information (within the U.K., see below) 


Follow ordering procedures for domestic ordering and add $6.00 for foreign post- 
age and handling. 


U.K. Ordering Information 


Send your order in writing along with £18.95 (includes VAT) to: Microsoft 
Press, 27 Wrights Lane, London W8 5TZ. You may pay by check or money 
order (payable to Microsoft Press) or by American Express, VISA, MasterCard, 
or Diners Club. (If paying by credit card, please include both your card number 
and the expiration date.) Specify 5.25-inch format or 3.5-inch format. 


Microsoft Press Companion Disk Guarantee 


If the disk proves defective, send the defective disk along with your packing slip 
(or copy) to: Microsoft Press, Consumer Sales, One Microsoft Way, Redmond, 
WA 98052-6399. 


If you have questions or comments about the files on the disk, send them to: 
Languages User Education, Microsoft Corporation, One Microsoft Way, Red- 
mond, WA 98052-6399. 


The Companion Disk for Microsoft C Run-Time Library Reference is available 
only from Microsoft Press. 
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Overview 


The first part of this book provides an overview of the run-time 
library provided with the Microsoft C Professional Development 
System. 


Chapter | is a general guide to the use of the run-time library 
routines. 


Chapter 2 lists the routines by category. 


Chapter 3 tells how to access global variables and types defined 
in the run-time library. 


Using C Library Routines 


CHAPTER 


This chapter provides basic information about how to use Microsoft C library 
routines. It also describes some special rules, such as file- and path-name conven- 
tions, that apply to particular routines. You should read this chapter before you 
begin to use C library routines, and you may also want to refer back to it if you 
have questions about library procedures. 


1.1 Calling Library Routines 


To use aC library routine, simply call it in your program, just as if it is defined 
there. For instance, suppose you write the following program and name it 
SAMPLE.C: 


#Hinclude <stdio.h> 
main() 
{ 


) 


The program prints Microsoft C_ by calling the printf routine, which is part 
of the standard C library. Calling a library routine normally involves two groups 
of files: , 


printf( “Microsoft C" ); 


1. Header (“include”) files that contain declarations and type definitions 
required by library routines 


2 Library files that contain the library routines in compiled form 


Header files and library files are both included with Microsoft C. Header files are 
used when compiling, and library files are used when linking. 
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You include the necessary header files in your program source code with 
#include directives. The description of each library routine in Part 2, “Refer- 
ence,” tells you what header file the routine requires. Since printf requires the 
STDIO.H header file, the SAMPLE.C program contains the following line: 


d#Hinclude <stdio.h> 


This line causes the compiler to insert the contents of STDIO.H into the source 
file SAMPLE.C. 


After you compile the source file, you link the resulting object (.OBJ) file with 
the appropriate library (.LIB) file to create an executable (.EXE) file. Your object 
file contains the name of every routine that your program calls, including library 
routines. If a routine is not defined in your program, the linker searches for its 
code in a library file and includes that code in the executable file. 


Normally, the code for standard library routines is contained in the “default li- 
brary” that you create when installing Microsoft C. Since the linker automat- 
ically searches the default library, you do not need to specify that library’s name 
when linking your program. The following command links the example program 
with the default library: 


link sample,,,; 


If you call a library routine that is not contained in the default library, you must 
give the linker the name of the library file that contains the routine. For instance, 
suppose your program uses a Microsoft C graphics routine and you did not make 
GRAPHICS.LIB part of your default library when installing Microsoft C. You 
would then link the program using a line like the following: 


link sample,,, graphics.1ib; 


For more information about libraries and linking, consult the installation docu- 
mentation for your compiler. 


1.2 Using Header Files 


As stated in the previous section, you should include C header files when using 
library routines. This section describes particular reasons why header files are 
required. 
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7.2.1 Emneneing Necessary Definitions 


Many C library routines use constants, type definitions, or macros defined in a 
header file. To use the routine, you must include the header file containing the 
needed definition(s). The following list gives examples: 


Definition Example 


Macro. If a library routine is implemented as a macro, the 
macro definition appears in a header file. For in- 
stance, the toupper macro is defined in the header 
file CTYPE.H. 


Manifest constant Many library routines refer to constants that are de- 
fined in header files. For instance, the open routine 
uses constants such as O_CREAT, which is defined 
in the header file FCNTL.H. 


Type definition Some library routines return a structure or take a 
structure as an argument. For example, stream 
input/output routines use a structure of type FILE, 
which is defined in STDIO.H. 


1.2.2 Including Function Declarations 


The Microsoft C header files also contain function declarations for every func- 
tion in the C library. These declarations are in the style recommended by the 
ANSI C standard. Given these declarations, the compiler can perform “type 
checking” on every reference to a library function, making sure that you have 
used the correct return type and arguments. Function declarations are sometimes 
called “prototypes,” since the declaration serves as a prototype or template for 
every subsequent reference to the function. 


A function declaration lists the name of the function, its return type, and the num- 
ber and type of its arguments. For instance, below is the declaration of the pow 
library function from the header file MATH.H: 


double pow( double x, double y ); 


The example declares that pow returns a value of type double and takes two ar- 
guments of type double. Given this declaration, the compiler can check every ref- 
erence to pow in your program to ensure that the reference passes two double 
arguments to pow and takes a return value of type double. 


The compiler can perform type checking only for function references that appear 
after the function declaration. Because of this, function declarations normally ap- 
pear near the beginning of the source file, prior to any use of the functions they 
declare. 
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Function declarations are especially important for functions that return a value of 
some type other than int, which is the default. For example, the pow function re- 
turns a double value. If you do not declare such a function, the compiler treats its 
return value as int, which can cause unexpected results. 


It is also a good practice to provide declarations for functions that you write. If 
you do not want to type the declarations by hand, you can generate them automat- 
ically by using the /Zg compiler option. This option causes the compiler to 
generate ANSI-standard function declarations for every function defined in the 
current source file. Redirect this output to a file, then insert the file near the 
beginning of your source file. 


Your program can contain more than one declaration of the same function, as 
long as the declarations do not conflict. This is important if you have old pro- 
grams whose function declarations do not contain argument-type lists. For in- 
stance, if your program contains the declaration 


char *calloc( ); 


you can later include the following declaration: 


char *calloc(unsigned, unsigned); 


Because the two declarations are compatible, even though they are not identical, 
no conflict occurs. The second declaration simply gives more information about 
function arguments than the second. A conflict would arise, however, if the decla- 
rations gave a different number of arguments or gave arguments of different 


types. 


Some library functions can take a variable number of arguments. For instance, 
the printf function can take one argument or several. The compiler can perform 
only limited type checking on such functions, a factor that affects the following 
library functions: 


u Incalls to cprintf, cscanf, printf, and scanf, only the first argument (the for- 
mat string) is type checked. 


m Incalls to fprintf, fscanf, sprintf, and sscanf, only the first two arguments 
(the file or buffer and the format string) are type checked. 


m Incalls to open, only the first two arguments (the path name and the open 
flag) are type checked. 


= Incalls to sopen, only the first three arguments (the path name, the open flag, 
and the sharing mode) are type checked. 
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w Incalls to execl, execle, execlp, and execlpe, only the first two arguments 
(the path name and the first argument pointer) are type checked. 


= Incalls to spawnl, spawnle, spawnlp, and spawnlpe, only the first three ar- 
guments (the mode flag, the path name, and the first argument pointer) are 
type checked. 


1.3 File Names and Path Names 


Many library routines take strings representing paths and file names as argu- 
ments. If you plan to transport your programs to the XENIX operating system, 
you should remember that XENIX uses file- and path-name conventions that are 
different from those used by DOS and OS/2. If you do not plan to ed a your 
programs to XENIX, you can skip this section. 


Case Sensitivity 


The DOS and OS/2 operating systems are not case sensitive (they do not dis- 
tinguish between uppercase and lowercase letters). Thus, SAMPLE.C and 
Sample.C refer to the same file in DOS and OS/2. However, the XENIX operat- 
ing system is case sensitive. In XENIX, SAMPLE.C and Sample.C refer to differ- 
ent files. To transport programs to XENIX, choose file and path names that work 
correctly in XENIX, since either case works in DOS and OS/2. For instance, the 
following directives are identical in DOS and OS/2, but only the second works in 
XENIX: 


#include <STDIO.H> 
dFinclude <stdio.h> 


Subdirectory Conventions 


Under XENIX, certain header files are normally placed in a subdirectory named 
SYS. Microsoft C follows this convention to ease the process of transporting pro- 
grams to XENIX. If you do not plan to transport your programs, you can place 
the SYS header files elsewhere. 


Path-Name Delimiters — 


XENIX uses the slash (/) in path names, while DOS and OS/2 use the backslash 
(\). To transport programs to XENIX, it is advantageous to use path-name 
delimiters that are compatible with XENIX whenever possible. 
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1.4 Choosing Between Functions and Macros 


This book uses the words “routine” and “function” interchangeably. However, 
the term “routine” actually encompasses both functions and macros. Because 
functions and macros have different properties, you should pay attention to 
which form you are using. The descriptions in the reference section indicate 
whether routines are implemented as functions or as macros. 


Most routines in the Microsoft C library are functions. They consist of compiled 
C code or assembled Microsoft Macro Assembler (MASM) code. However, a 
few library routines are implemented as macros that behave like functions. You 
can pass arguments to library macros and invoke them in the same way you in- 
voke functions. 


The main benefit of using macros is faster execution time. A macro is expanded 
(replaced by its definition) during preprocessing, creating in-line code. Thus, 
macros do not have the overhead associated with function calls. On the other 
hand, each use of a macro inserts the same code in your program, whereas a func- 
tion definition occurs only once regardless of how many times it is called. Func- 
tions and macros thus offer a trade-off between speed and size. 


Apart from speed and size issues, macros and functions have some other impor- 
tant differences: 


m= Some macros treat arguments with side effects incorrectly when the macro 
evaluates its arguments more than once (see the example that follows this 
list). Not every macro has this effect. To determine if a macro handles side ef- 
fects as desired, examine its definition in the appropriate header file. 


m= A function name evaluates to an address, but a macro name does not. Thus, 
you cannot use a macro name in contexts requiring a function pointer. For in- 
stance, you can declare a pointer to a function, but you cannot declare a 
pointer to a macro. 


m You can declare functions, but you cannot declare macros. Thus, the compiler 
cannot perform type checking of macro arguments as it does of function argu- 
ments. However, the compiler can detect when you pass the wrong number of 
arguments to a macro. 


= You must always include the appropriate header file when using a library 
macro. Every library macro is defined with a #define directive in a header 
file. If you do not include the header file, the macro is undefined. 
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The following example demonstrates how some macros can produce unwanted 
side effects. It uses the toupper routine from the standard C library. 


#Finclude <ctype.h> 


= 'm's 


nt a 
toupper(at+) ; 


oct 


i 
a 


The example increments a when passing it as an argument to the toupper 
routine, which is implemented as a macro. It is defined in CTYPE.H: 


#idefine toupper(c) ( (islower(c)) ? _toupper(c) : (c) ) 


The definition uses the conditional operator (? :). The conditional expression 
evaluates the argument c twice: once to check if it is lowercase and again to cre- 
ate the result. This macro evaluates the argument a++ twice, increasing a by 2 
instead of 1. As a result, the value operated on by islower differs from the value 
operated on by _toupper. . 


Like some other library routines, toupper is provided in both macro and function 
versions. The header file CTYPE.H not only declares the toupper function but 
also defines the toupper macro. 


Choosing between the macro version and function version of such routines is 
easy. If you wish to use the macro version, you can simply include the header file 
that contains the macro definition. Because the macro definition of the routine al- 
ways appears after the function declaration, the macro definition normally takes 
precedence. Thus, if your program includes CTYPE.H and then calls toupper, 
the compiler uses the toupper macro: 


#Hinclude <ctype.h> 


int a= 'm'; 
= toupper(a); 


You can force the compiler to use the function version of a routine by enclosing 
the routine’s name in parentheses: 


#Hinclude <ctype.h> 


Because the name toupper is not immediately followed by a left parenthesis, the 
compiler cannot interpret it as a macro name. It must use the toupper function. 
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A second way to do this is to “undefine” the macro definition with the #undef 
directive: 


#Hinclude <ctype.h> 
#tundef toupper 


Since the macro definition no longer exists, subsequent references to toupper 
use the function version. 


A third way to make sure the compiler uses the function version is to declare the 
function explicitly: 


#Hinclude <ctype.h> 
int toupper(int _c); 


Since this function declaration appears after the macro definition in CTYPE.H, it 
causes the compiler to use the toupper function. 


7.5 Stack Checking on Entry — 


For certain library routines, the compiler performs stack checking on entry. (The 
“stack” is a memory area used for temporary storage.) Upon entry to such a 
routine, the stack is checked to determine if it has enough room for the local vari- 
ables used by that routine. If it does, space is allocated by adjusting the stack 
pointer, Otherwise, a “stack overflow” run-time error occurs. If stack checking is 
disabled, the compiler assumes there is enough stack space; if there is not, you 
might overwrite memory locations in the data segment and receive no warning. 


Typically, stack checking is enabled only for functions with large local-variable 
requirements (more than about 150 bytes), since there is enough free space be- 
tween the stack and data segments to handle functions with smaller requirements. 
If the function is called many times, stack checking slows execution slightly. 


_ Stack checking is enabled for the following library functions: 


execvp scanf system 
execvpe spawnvp vprintf . 
fprintf spawnvpe write 
fscanf sprintf 


printf sscanf 
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7.6 Handling Errors 


Many library routines return a value that indicates an error condition. To avoid 
unexpected results, your code should always check such error values and handle 
all of the possible error conditions. The description of each library routine in the 
reference section lists the routine’s return value(s). 


Some library functions do not have a set error return. These include functions 
that return nothing and functions whose range of return values makes it im- 
possible to return a unique error value. To aid in error handling, some functions 
in this category set the value of a global variable named errno. 


If the reference description of a routine states that it sets the errno variable, you 
can use errno in two ways: 


1. Compare errno to the values defined in the header file ERRNO.H. 


2. Handle errno with the perror or strerror library routines. The perror 
routine prints a system error message to the standard error (stderr). The 
strerror routine stores the same information in a string for later use. 


When you use errno, perror, and strerror, remember that the value of errno re- 
flects the error value for the last call that set errno. To avoid confusion, you 
should always test the return value to verify that an error actually occurred. Once 
you determine that an error has occurred, use errno or perror immediately. 
Otherwise, the value of errno may be changed by intervening calls. 


Library math routines set errno by calling the matherr or _matherrl library 
routines, which are described in the reference section. If you wish to handle math 
errors differently from these routines, you can write your own routine and name 
it matherr or _matherrl. Your routine must follow the rules listed in the 
matherr reference description. 


The ferror library routine allows you to check for errors in stream input/output 
operations. This routine checks if an error indicator has been set for a given 
stream. Closing or rewinding the stream automatically clears the error indicator. 
You can also reset the error indicator by calling the clearerr library routine. 


The feof library routine tests for end-of-file on a given stream. An end-of-file 
condition in low-level input and output can be detected with the eof routine or 
when a read operation returns 0 as the number of bytes read. 


The _grstatus library routine allows you to check for errors after calling certain 
graphics library operations. See the reference page on the _ grstatus function for 
details. 
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1.7 Operating-System Considerations 


The library routines listed in this section behave differently under different oper- 
ating system versions. For more information on an individual routine, see the de- 
scription of that routine in the reference section. 


Routine - Restrictions 

locking These routines are effective only in OS/2 and in 
sopen DOS versions 3.0 and later. 

_fsopen 

dosexterr The dosexterr routine provides error handling for 


system call 0x59 (get extended error) in DOS ver- 
sions 3.0 and later. 


dup The dup and dup? routines can cause unexpected re- 
dup2 sults in DOS versions earlier than 3.0. If you use 
dup or dup2 to create a duplicate file handle for 
stdin, stdout, stderr, stdaux, or stdprn, calling the 
close function with one handle causes errors in later 
I/O operations that use the other handle. This 
anomaly does not occur in OS/2 or in DOS versions 


3.0 and later. | 
exec When using the exec and spawn families of func- 
spawn tions under DOS versions earlier than 3.0, the value 


of the arg0 argument (or argv[0] to the child 
process) is not available to the user; a null string 
("") is stored in that position instead. In OS/2, the 
arg0 argument contains the command name; in DOS 
versions 3.0 and later, it contains the complete com- 
mand path. 


Microsoft C defines global variables that indicate the version of the current oper- 
ating system. You can use these to determine the operating-system version in 
which a program is executing. See Chapter 3, “Global Variables and Standard 
Types,” for more information. 
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1.8 Floating-Point Support 


Microsoft math library routines require floating-point support to perform calcula- 
tions with real numbers (numbers that can contain fractions). This support can be 
provided by the floating-point libraries that accompany your compiler software 
or by an 8087, 80287, or 80387 coprocessor. The names of the functions that re- 
quire floating-point support are listed below: 


acos cos’ fmodl powl 
acosl cosl fmsbintoieee sin 

asin cosh _fpreset sinl 
asinl coshl  — frexp sinh 
atan dieeetomsbin frexpl sinhl 
atanl difftime gcevt sqrt 
atan2 dmsbintoieee hypot sqrtl 
atan2I ecvt hypotl _Status87 
atof - exp Idexp strtod 
_atold expl Idexpl _strtold 
bessel fabs log tan 
cabs fabsl logl tanl 
cabsl fevt log10 tanh 
ceil fieeetomsbin log101 tanhl 
ceill floor modf 

_clear87 floorl modfl 

_control87 fmod pow 


Note that the bessel routine does not correspond to a single function, but to 
twelve functions named jo, jl, jn, yO, yl, yn, jOl, jill, _jnl, yOl, yl, and 
_ynil. Also note that the _clear87 and _control87 functions are not available with 
the /FPa compiler option. 


Also requiring floating-point support is the printf family of functions (cprintf, 
fprintf, printf, sprintf, vfprintf, vprintf, and vsprintf). These functions require 
support for floating-point input and output if used to print floating-point values. 


The C compiler tries to detect whether floating-point values are used in a pro- 
gram so that supporting functions are loaded only if required. This behavior 
saves a considerable amount of space for programs that do not require floating- 
point support. 


When you use a floating-point type specifier in the format string for a printf or 
scanf call, make sure you specify floating-point values or pointers to floating- 
point values in the argument list. These must correspond to any floating-point - 
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type specifiers in the format string. The presence of floating-point arguments al- 
lows the compiler to detect that floating-point support code is required. If a 
floating-point type specifier is used to print an integer argument, for example, 
floating-point values will not be detected because the compiler does not actually 
read the format string used in the printf and scanf functions. For instance, the fol- 
lowing program produces an error at run time: 


main( ) /* This example causes an error */ 
{ 

long f = 1@L; a 

printf("2f", f); 
} 


In the preceding example, the functions for floating-point support are not loaded 
because 


a No floating-point arguments are given in the call to printf. 


= No floating-point values are used elsewhere in the program. 


As aresult, the following error occurs: 


Floating point not loaded 


Here is a corrected version of the above call to printf in which the long integer 
value is cast to double: 


main( ) /* This example works correctly */ 
( 
long f = 1@L; 
printf("%f", (double) f); 
} 


7.9 Using Huge Arrays with Library Functions 


In programs that use small, compact, medium, and large memory models, Micro- 
soft C allows you to use arrays exceeding the 64K (kilobyte) limit of physical 
memory in these models by explicitly declaring the arrays as huge. However, 
generally, you cannot pass _huge data items as arguments to C library functions. 
In the compact-model library used by compact-model programs and in the large- 
model library used by both large-model and huge-model programs, only the func- 
tions listed below use argument arithmetic that works with _huge items: 


bsearch _fmemchr _fmemmove lfind 
fread _fmemcmp _fmemset Isearch 
fwrite _fmemcpy halloc memecpy 


_fmemccpy _fmemicmp hfree memchr 


Using C Library Routines 17 


With this set of functions, you can read from, write to, search, sort, copy, initial- 
ize, compare, or dynamically allocate and free huge arrays; the huge array can 
be passed without difficulty to any of these functions in a compact-, large-, or 
huge-model program. The model-independent routines in the above list (those 
beginning with _f) are available in all memory models. 


The memset, memepy, and memcemp library routines are available in two ver- 
sions: as C functions and as intrinsic (in-line) code. The function versions of 
these routines support huge pointers in compact and large memory models, but 
the intrinsic versions do not support huge pointers. (The function version of such 
routines generates a call to a library function, whereas the intrinsic version in- 
serts in-line code into your program. Your compiler documentation explains how 
to select the intrinsic versions of library routines.) 


CHAPTER 


Run-Time Routines 
by Category 


Microsoft C library routines handle various kinds of tasks. If you know the type 
of task you need done, but don’t know exactly which routine to use, the catego- 
rized lists of routines in this chapter can help. 


The descriptions here are intended only to give you a brief overview of the capa- 
bilities of the run-time library. For a complete description of the behavior, syn- 
tax, and use of each routine, see Part 2, “Run-Time Functions.” 


The main categories of library routines are 
= Buffer manipulation 

m Character classification and conversion 
m= Data conversion 

m Directory control 

a File handling 

= Graphics 

m Input and output 

m Internationalization 

a Math 

= Memory allocation 

m Process and environment control 

m Searching and sorting 

a String manipulation 

m System calls 

= Time 


ms Variable-length argument lists 
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2.1 Buffer Manipulation 


The buffer-manipulation routines are useful for working with areas of memory 
on a character-by-character basis. A “buffer” is an array of characters, similar 
to a character string. However, unlike strings, buffers are not usually termi- 
nated with a null character (°\0’). Therefore, the buffer-manipulation routines 
always take a length or count argument. Function declarations for the buffer- 
manipulation routines are given in the include files MEMORY.H and 
STRING.H, with an exception being the swab function, which appears in 


STDLIB.H. 


Routines beginning with _f are model independent; the _f stands for far. These 
routines are useful in writing mixed-model programs because they can be called 
from any program, regardless of the memory model being used. 


Routine 
-Mmemccpy, 
_fmemccpy 


memchr, _fmemchr 


memcmp, _fmemcmp 
memcpy, _fmemepy 


memicmp, 
_fmemicmp 


memmove, 
_fmemmove 


memset, _fmemset 


swab 


Use 


Copy characters from one buffer to another until a 
given character or a given number of characters has 
been copied 


Return a pointer to the first occurrence, within a 
specified number of characters, of a given character 
in the buffer 


Compare a specified number of characters from two 
buffers 


Copy a specified number of characters from one 
buffer to another 


Compare a specified number of characters from two 
buffers without regard to the case of the letters (up- 
percase and lowercase treated as equivalent) 


Copy a specified number of characters from one 
buffer to another . 


Use a given character to initialize a specified num- 
ber of bytes in the buffer . 


Swaps bytes of data and stores them at the specified 
location 
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When the source and target areas overlap, only the memmove and _fmemmove 
functions are guaranteed to copy the full source properly. (The memepy and 
_fmemepy routines do not always copy the full source in such cases.) 


2.2 Character Classification and Conversion 


The character classification and conversion routines allow you to test individual 
characters in a variety of ways and to convert between uppercase and lowercase 


characters. 

Routine Use 

isalnum Tests for alphanumeric character 

isalpha Tests for alphabetic character 

isascii Tests for ASCII character 

iscntrl Tests for control character 

isdigit Tests for decimal digit 

isgraph Tests for printable character except space 

islower . Tests for lowercase character 

isprint Tests for printable character 

ispunct Tests for punctuation character 

isspace | Tests for white-space character 

isupper Tests for uppercase character 

isxdigit Tests for hexadecimal digit 

toascii Converts character to ASCII code 

tolower Tests character and converts to lowercase if 
uppercase 

_tolower Converts character to lowercase (unconditional) 

toupper Tests character and converts to uppercase if 
lowercase 


_toupper Converts character to uppercase (unconditional) 
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The classification routines identify characters by finding them in a table of classi- 
fication codes. Using these routines to classify characters is generally faster than 
writing a test expression such as the following: 


if ((c >= B) || ¢ <= Ox7f)) 


All of these routines are implemented in two versions: as functions and as mac- 
ros. The function prototypes and macro definitions appear in CTYPE.H. Section 
1.4, “Choosing Between Functions and Macros,” explains how to choose the 
appropriate version. The toupper and tolower functions are also declared in the 
STDLIB.H header file. 


2.3 Data Con version 


The data-conversion routines convert numbers to strings of ASCII characters 
and vice versa. These routines are implemented as functions, all of which are de- 
clared in the include file STDLIB.H. The atof function, which converts a string 
to a floating-point value, is also declared in MATH.H. 


Routine Use 

abs Finds absolute value of integer 
atof Converts string to float 

atoi Converts string to int 

atol Converts string to long 

_atold Converts string to long double 
ecvt Converts double to string 

fevt Converts double to string 

gevt Converts double to string 

itoa | Converts int to string 

labs Finds absolute value of long integer 
Itoa Converts long to string 


strtod Converts string to double 
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strtol Converts string to a long integer 

_strtold Converts string to long double 

strtoul Converts string to an unsigned long integer 
ultoa Converts unsigned long to string 


2.4 Directory Control 


The directory-control routines let a program access, modify, and obtain informa- 
tion about the directory structure. These routines are functions and are declared 


in DIRECT.H. 

chdir Changes current working directory 

_chdrive Changes current drive 

getcwd Gets current working directory 

_getdcwd Gets current working directory for the specified drive 
_getdrive Gets the current disk drive 

mkdir Makes a new directory 

rmdir Removes a directory 

_searchenv Searches for a given file on specified paths 


2.5 File Handling 


The file-handling routines let you create, manipulate, and delete files. They also 
set and check file-access permissions. 


File-handling routines work on a file designated by a path name or by a “file 
handle,” an integer assigned by the operating system that identifies an open file. 
These routines modify or give information about the designated file. Most of 
them are declared in the include file IO.H, with the exceptions being the fstat 
and stat functions (declared in SYS\STAT.H), the _fullpath routine (declared in 
DIRECT.H), and the remove and rename functions (also declared in STDIO.H). 
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access 
chmod 
chsize 
filelength 
fstat 
_fullpath 


isatty 
locking 


_makepath 


mktemp 
remove 
rename 
setmode 
_splitpath 
stat 
umask 


unlink 


Use 

Checks file-permission setting 
Changes file-permission setting 
Changes file size 

Gets file length 

Gets file-status information on handle 


Makes an absolute path name from a relative 
path name 


Checks for character device 


Locks areas of file (available with OS/2 and 
DOS versions 3.0 and later) 


Merges path-name components into a single, full 
path name 


Creates unique file name 

Deletes file 

Renames file 

Sets file-translation mode 

Splits a path name into component pieces 
Gets file-status information on named file 
Sets default-permission mask 


Deletes file 


The access, chmod, _fullpath, makepath, remove, rename, _splitpath, stat, 
and unlink routines operate on files specified by a path name or file name. 


The chsize, filelength, fstat, isatty, locking, and setmode routines work with 
files designated by a file handle. 


The mktemp and umask routines have functions that are slightly different from 
the other routines. The mktemp routine creates a unique file name, and the pro- 
grammer can use mktemp to create unique file names that do not conflict with 
the names of existing files. The umask routine sets the default permission mask 
for any new files created in a program. The mask can override the permission set- 
ting given in the open or creat call for the new file. ; 
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2.6 Graphics 


Microsoft C graphics routines offer a wide variety of graphics functions, low- 
level graphics primitives, font functions, and presentation graphics (displays such 
as graphs and pie charts). 


Graphics functions are supplied in two libraries that must be explicitly linked 
with your program. The GRAPHICS.LIB library provides support for low-level 
graphics and character-font routines. The library PGCHART.LIB supports 
presentation-graphics routines. 


2.6.1 Low-Level Graphics and Character-Font Functions 


The low-level graphics and font functions are declared in the include file 


GRAPH.H. 


The library can be divided into the eight categories listed below, which corre- 
spond to the different tasks involved in creating and manipulating graphic objects. 


Most graphics routines work only in DOS. Two categories of routines (“configur- 
ing mode and environment” and “creating text output”) work in OS/2 as well 


as DOS. 


Category 


Configuring mode and 


environment (OS/2 
and DOS) 


Setting coordinates 


Setting low-level 
graphics palettes 


Setting attributes 


Creating graphics 
output 


Creating text output 
(OS/2 and DOS) 


Transferring images 


Displaying fonts 


Task 


Select the proper display mode for the hardware and 
establish memory areas for writing and displaying of 
images 


Specify the logical origin and the active display area 
within the screen 


Specify a palette mapping for low-level graphics 
routines 


Specify background and foreground colors, fill 
masks, and line styles for low-level graphics routines 


Draw and fill figures 
Write text on the screen 
Store images in memory and retrieve them 


Display text in character fonts compatible with 
Microsoft Windows™ 


The following sections explain each of these categories. 
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2.6.1.1 Configuring Mode and Environment 


-Routines that configure the mode and environment establish the graphics or text 
mode of operation, determine the current graphics environment, and control the 


display of the cursor. 


All of the routines listed in this section are available in OS/2 as well as DOS. 


Routine 


_clearscreen 


_getactivepage 
_getbkcolor 
_getvideoconfig 
_getvisualpage 


_grstatus 
_setactivepage 


_setbkcolor 
_Settextrows 
_Setvideomode 


_setvideomoderows 


_Setvisualpage 


Use 


Erases the screen and fills it with the current back- 
ground color 


Gets the current active page number 

Returns the current background color 

Obtains status of current graphics environment 
Gets the current visual page number 


Returns the status of the most recent graphics func- 
tion call 


Sets memory area for the active page for writing 
images 


Sets the current background color 
Sets the number of text rows 
Selects an operating mode for the display screen 


Sets the video mode and the number of rows for text 
operations 


Sets memory area for the current visual page 


2.6.1.2 Setting Coordinates 


The “set coordinates” routines set the current text or graphics position and con- 
vert pixel coordinates between the various graphic coordinate systems. 


The Microsoft C graphics functions recognize three sets of coordinates: 


1. Fixed physical coordinates 


2. View coordinates defined by the application 


3. Window coordinates that can include floating-point values 
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The functions in this category establish window and view coordinate systems and 
translate between physical, view, and window coordinate systems. 


Routine Use 
_getcurrentposition Determines current position in view coordinates 


_getcurrentposition_w Determines current position in window coordinates 


_getphyscoord — Converts view coordinates to physical coordinates 

_getviewcoord Converts physical coordinates to view coordinates 

_getviewcoord_w Converts window coordinates to view coordinates 

_getviewcoord_wxy Converts window coordinates in _wxycoord struc- 
ture to view coordinates 

_getwindowcoord Converts view coordinates to window coordinates 

_setcliprgn Limits graphic output to a region of the screen 

_setvieworg Positions the view-coordinate origin 

_setviewport Limits graphics output to a region of the screen and 


positions the view-coordinate origin to the upper-left 
corner of that region 


_setwindow Defines a floating-point window coordinate system 


The default view coordinate system is identical to the physical screen coordinate 
system. The physical origin (0, 0) is always in the upper-left corner of the dis- 
play. The x axis extends in the positive direction left to right, while the y axis ex- 
tends in the positive direction top to bottom. 


The physical horizontal and vertical dimensions depend on the hardware display 
configuration and the selected mode. These values are accessible at run time by 
examining the numxpixels and numypixels fields of the videoconfig structure 
returned by _getvideoconfig. (The _getvideoconfig routine is listed in the pre- 
vious section. ) 


The _setvieworg function allows you to move the viewport origin to a new posi- 
tion relative to the physical screen. 


Routines that refer to coordinates on the physical screen or viewport require in- 
teger values. However, in real-world graphing applications, you might wish to 
use floating-point values, such as stock prices or average rainfall. The window 
coordinate system allows you to display graphics using floating-point values in- 
stead of integers. 


The _getcurrentposition and _getcurrentposition_w routines allow you to de- 
termine the location of the current graphics-output point. 
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The _setcliprgn function defines a restricted active display area on the screen. 
The _setviewport function does the same thing and also resets the viewport 
origin to the upper-left corner of the restricted active display area. 


The physical coordinates of any view-coordinate point can be determined with 
the _getphyscoord function, and the view coordinates of any physical point can 
be determined with the _getviewcoord function. 


The view coordinates of any window coordinate can be determined with the 
_getviewcoord_ wand _getviewcoord_wxy functions. The window coordinates 
of any view coordinate can be determined with the _getwindowcoord function. 


The _setwindow function defines the current viewport as a real-coordinate win- 
dow bound by the specified floating-point values. 


2.6.1.3 Setting Low-Level Graphics Palettes 


Use the low-level palette routines to select or remap color palettes. 


Routine Use 
-_remapallpalette Changes all color indexes in the current palette 
_remappalette Changes a single color index in the current palette 
_Selectpalette Selects a predefined palette 


Some video modes support a “color palette,” which is a table of the color values 
that can be displayed together on the screen at any given time. A “color value” is 
a long integer representing a color that can be displayed on your system. 


In CGA color graphics modes, you can use the _selectpalette routine to choose 
one of several predefined palettes. 


On EGA and VGA video systems, you can “remap” (change) the palette using 
the remappalette or_remapallpalette routines. For instance, the EGA 
_ERESCOLOR mode offers a total of 64 color values, of which 16 can be dis- 
played at a time. In this mode, the palette contains 16 “color indices,” or slots to 
which you can assign color values. 


The _remappalette routine changes a single color index to a specified color 
value. The _remapallpalette routine changes all of the available palette entries 
simultaneously. 


2.6.1.4 Setting Attributes 


The low-level output functions that draw lines, arcs, ellipses, and other basic 
figures do not specify color or line-style information. Instead, the low-level 
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graphics functions rely on a set of attributes that are set independently by the fol- 
lowing functions: 


Routine Use 

_getarcinfo Determines the endpoints in viewport coordinates of 
the most recently drawn arc or pie 

_getcolor Gets the current color 

_getfillmask Gets the current fill mask 

_getlinestyle Gets the current line-style mask 

_getwritemode Gets the current logical write mode 

_setcolor Sets the current color 

_setfillmask Sets the current fill mask 

_setlinestyle Sets the current line-style mask 

_setwritemode Sets logical write mode for line drawing 


The _getcolor and _setcolor functions get or set the current color index for 
graphics and font output. The _getbkcolor and _setbkcolor functions get or set 
the current background color. 


The _getfillmask and _setfillmask functions get or set the current fill mask. The 
mask is an 8-by-8-bit template array, with each bit representing a pixel. If a bit is 
O, the pixel in memory is left untouched, as the mask is transparent to that pixel. 
If a bit is 1, the pixel is assigned the current color value. The template is repeated 
as necessary over the entire fill area. 


The _getlinestyle and _setlinestyle functions get or set the current line style. The 
line style is determined by a 16-bit template buffer with each bit corresponding 
to a pixel. Ifa bit is 1, the pixel is set to the current color. If a bit is 0, the pixel is 
not changed. The template is repeated for the length of the line. 


The _getwritemode and _setwritemode functions get or set the logical write 
mode for straight line drawing. The default mode, _GPSET, causes lines to be 
drawn in the current graphics color. Other modes combine the current graphics 
color and the original screen image using various logical operations. 


2.6.1.5 Creating Graphics Output 


The graphics output functions use a set of specified coordinates and draw various 
figures. They use the current or default attributes for line-style mask, fill mask, 
write mode, background color, and foreground color. 
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The name of each function announces its task or the figure it draws, as the follow- 
ing list indicates: 


Routine Use 

_are, _arc_w, _arc_wxy Draw an arc 

_ellipse, _ellipse_w, Draw an ellipse or circle 

_ellipse_wxy 

_floodfill, _floodfill_w Flood-fill an area of the screen with 
the current color 

_getcurrentposition, Obtain the current graphic-output 

_getcurrentposition_w position used by _lineto and 
_outgtext 

_getpixel, _getpixel_w Obtain a pixel’s color 

_lineto, _lineto_w Draw a line from the current graphic 
output position to a specified point 

_moveto, _moveto_w Move the current graphic-output posi- 
tion to a specified point 

_pie, _pie_w, _pie_wxy Draw a pie-slice-shaped figure 

_polygon, _polygon_w, Draw or scan-fill a polygon 

_polygon_wxy 

_rectangle, _rectangle_w, Draw or scan-fill a rectangle 


_rectangle_wxy 


_Setpixel, _setpixel_w Set a pixel’s color 


Most of these routines are available in several forms, which are indicated by their 
names. Output functions without a suffix use the view coordinate system. Func- 
tions that end with _w take double values as arguments and use the window 
coordinate system. Functions that end with _wxy use _wxycoord structures to de- 
fine the coordinates and use the window coordinate system. 


Circular figures, such as arcs and ellipses, are centered within a “bounding rec- 
tangle” specified by two points that define the diagonally opposed corners of the 
rectangle. The center of the rectangle becomes the center of the figure, and the 
rectangle’s borders determine the size of the figure. 


2.6.1.6 Creating Text Output 


The next group of routines provides text output in both graphics and text modes. 
Unlike the standard console I/O library routines, these functions. recognize text- 
window boundaries and use the current text color. 
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All of the routines listed in this section work in OS/2 as well as DOS. 


Routine Use 

_displaycursor Sets the cursor on or off upon exit from a graphics 
routine 

_gettextcolor Obtains the current text color 

_gettextcursor Returns the current cursor attribute (text modes only) 

_gettextposition Obtains the current text-output position 

_gettextwindow Gets the current text window boundaries 

_outmem Prints text of a specified length from a memory 
buffer 

_outtext Outputs a text string to the screen at the current text 
position 

_scrolltextwindow Scrolls the current text window up or down 

_settextcolor Sets the current text color 

_settextcursor Sets the current cursor attribute (text modes only) 

_Settextposition Relocates the current text position 

_Settextwindow — Defines the current text-display window 

_Wwrapon Enables or disables line wrap 


H 


ad 
The _outtext and _outmem routines provide no formatting. If you want to out- 
put integer or floating-point values, you must convert the values into a string vari- 
able (using the sprintf function) before calling these routines. 


The _outtext routine recognizes the \n (newline character) and \r (carriage re- 
turn) sequences. The _outmem routine treats these sequences as printable 
graphics characters. 


2.6.1.7 Transferring Images 


The functions in this category transfer screen images between memory and the 
display, using a buffer allocated by the application, or determine the size in bytes 
of the buffer needed to store a given image. 


The functions that end with _w or _wxy use window coordinates; the other func- 
tions in this set use view coordinates. 
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Routine 


_getimage, 
_getimage_w, 
_getimage_wxy 
_imagesize, 
_imagesize_w, 
_imagesize_wxy 
_putimage, 
_putimage_w 


Use 


Store a screen image in memory 


Return the size (in bytes) of the buffer needed to 
store the image 


Retrieve an image from memory and. display it 


In some cases, the buffer needed to store an image with the _getimage functions 
must be larger than 64K (65,535) bytes. Use the halloc routine to allocate a buff- 


er larger than 64K. 


2.6.1.8 Displaying Fonts 


The functions listed in this section control the display of font-based characters on 


the screen. 


Routine 
_getfontinfo 


_getgtextextent 


_getgtextvector 


_outgtext 
_registerfonts 


_setfont 


_setgtextvector 


_unregisterfonts 


Use 
Obtains the current font characteristics 


Determines the width in pixels of specified text in 
the current font 


Gets orientation of font text output 


Outputs text in the current font to the screen at the 
specified pixel position 


Initializes font library 


Finds a single font that matches a specified set of 
characteristics and makes this font the current font 
for use by the _outgtext function 


Sets the current orientation for font text output 


Frees memory allocated by _registerfonts 


2.6.2 Presentation-Graphies Functions 


The presentation-graphics functions are declared in the PGCHART.H include 
file. The library can be divided into the three categories listed below, correspond- 
ing to the different tasks involved in creating and manipulating graphic objects: 


Category 


Displaying presen- 
tation graphics 


Analyzing 
presentation-graphics 
data 


Manipulating 
presentation-graphics 
structures 
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Task 


Initialize video structures for presentation graphics 
and establishes the default chart type. Display 
presentation-graphics chart: bar, column, pie, scat- 
ter, or line chart. 


Analyze data (does not display chart). 


Modify basic chart structures (e.g., palettes, cross- 
hatching styles). 


2.6.2.1 Displaying Presentation Graphics 


The functions listed in this section initialize the presentation-graphics library and 
display the specified graph type. 


Because the _pg_initchart routine initializes the presentation-graphics library, it 
must be called before any other function in the presentation-graphics library. The 
_pg_defaultchart function initializes the variables in the chart environment. 


The other routines in this category display the specified graph. The single-series 


versions plot one set of data, and the multiseries versions (those ending with an 
ms suffix) plot several sets of data in the same chart style. 


Presentation-graphics programs can display text in different font sizes by taking 
advantage of font-based characters (see Section 2.6.1.8, “Displaying Fonts.”) 
Call the _registerfonts and _setfont routines to select a font before calling the . 
_pginitchart routine. Subsequent charts use the selected font. You can later call 
the _unregisterfonts routine to restore the default character font and free the 
memory previously allocated for fonts. 


. _pg_chart 
_pg_chartms 
_pg_chartpie 
_pg_chartscatter 


_pg_chartscatterms 
_pg_defaultchart 


_pg_initchart 


Use 

Displays a single-series bar, column, or line chart 
Displays a multiseries bar, column, or line chart 
Displays a pie chart 

Displays a scatter diagram for a single series of data 


Displays a scatter diagram for more than one series 
of data 


Initializes all necessary variables in the chart en- 
vironment for a specified chart type 


Initializes the presentation-graphics library 
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2.6.2.2 Analyzing Presentation-Graphics Charts 


These routines calculate default values for the specified graph type but do not dis- 
play the chart. The single-series versions analyze one set of data, and the multi- 
series versions analyze several sets of data in the same chart style. 


Routine 


_pg_analyzechart 
_pg_analyzechartms 


_pg_analyzepie 
_pg_analyzescatter 


_pg_analyzescatterms 


Use 


Analyzes a single series of data for a bar, column, or 
line chart 


Analyzes a multiseries of data for a bar, column, or 
line chart 


Analyzes data for a pie chart 
Analyzes a single series of data for a scatter diagram 


Analyzes a multiseries of data for a scatter diagram 


2.6.2.3 Manipulating Presentation-Graphics Structures 


These functions control low-level aspects of the presentation-graphics package. 


_pg_hlabelchart 
_pg_viabelchart 
_pg_getpalette 


_pg_setpalette 
_pg_resetpalette 
_pg_getstyleset 


_pg_setstyleset 
_pg_resetstyleset 


_pg_getchardef 


_pg_setchardef 


Use 
Writes text horizontally on the screen 
Writes text vertically on the screen 


Retrieves current colors, line styles, fill patterns, and 
plot characters for all presentation-graphics palettes 


Sets current colors, line styles, fill patterns, and plot 
characters for all presentation-graphics palettes 


Sets current colors, line styles, fill patterns, and plot 
characters to the default values for the current screen 
mode 


Retrieves the contents of the current styleset 
Sets the contents of the current styleset 


Resets the contents of the current styleset to the de- 
fault value for the current screen mode 


Retrieves the current 8-by-8-pixel bit map for a 
specified character 


Sets the 8-by-8-pixel bit map for a specified 
character 
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2./ Input and Output 


The input and output (I/O) routines of the standard C library allow you to read 
and write data to and from files and devices. In C, there are no predefined file 
structures; all data items are treated as sequences of bytes. The following three 
types of I/O functions are available: 


1. Stream 
2. Low-level 


3. Console and port 


The “stream” I/O functions treat data as a stream of individual characters. By 
choosing among the many stream functions available, you can process data in 
different sizes and formats, from single characters to large data structures. Stream 
I/O also provides buffering, which can significantly improve performance. 


The “low-level” I/O routines do not perform buffering and formatting. Instead, 
they invoke the operating system’s input and output capabilities directly. These 
routines let you access files and peripheral devices at a more basic level than the 
stream functions. 


The “console and port” I/O routines allow you to read or write directly to a con- 
sole (keyboard and screen) or an I/O port (such as a printer port). The port I/O 
routines simply read and write data in bytes. With console I/O routines, some ad- 
ditional options are available, such as detecting whether a character has been 
typed at the console. You can also choose between echoing characters to the 
screen as they are read or reading characters without echoing. 


The C library also provides a number of direct DOS I/O system call routines. 
These are described in Section 2.14, “System Calls.” 


File I/O operations can be performed in two modes: text or binary. The following 
section describes these modes and their use. 


WARNING Because stream routines are buffered and low-level routines are not, the two 
types of routines are generally incompatible. You should use either stream or low-level 
routines consistently for processing a given file. 


2.7.1 Text and Binary Modes 


Many C programs use data files for input and output. Under DOS and OS/2, data 
files are normally processed in text mode. In this mode, each carriage-return—line- 
feed (CR-LF) combination is translated into a single line-feed character during 
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input. During output, each line-feed character is translated into a CR-LF 
combination. 


Sometimes you may want to process a file without making those translations. In 
these cases you use binary mode, which suppresses CR-LF translations. 


You can control the file translation mode in the following ways: 


a To process a few selected files in binary mode, while retaining the default 
text mode for most files, you can specify binary mode when you open the 
selected files. The fopen routine opens a file in binary mode when you 
specify the letter b in the access-mode string for the file. The open routine 
opens a file in binary mode when you specify the O_BINARY flag in the oflag 
argument. For more information about fopen and open, see the reference de- 
scription of each routine. 


= To process most or all files in binary mode, you can change the default mode 
to binary. The global variable _fmode controls the default translation mode, 
which is normally text. If you set _fmode to O_BINARY, the default mode is 
binary except for stdaux and stdprn, which are opened in binary mode by 
default. 


You can change the value of _fmode in two ways: 


1. Link with the file BINMODE.OBJ (supplied with Microsoft C). This changes 
_ the initial setting of _fmode to the O_BINARY flag, causing all files except 
stdin, stdout, and stderr to be opened in binary mode. 


2. Change the value of _fmode directly by setting it to the O_BINARY flag in 
your program. This has the same effect as linking with BINMODE.OBJ. 


You can still override the default mode (now binary) for a particular file by open- 
ing it in text mode. Specify the letter t when using fopen, or specify the O_TEXT 
flag when using open. 


By default, the stdin, stdout, and stderr files are opened in text mode, and the 
stdaux and stdprn files are opened in binary mode. The setmode routine allows 
you to change these defaults or change the mode of a file after it has been 
opened. See the reference description of setmode for details. 


2./.2 Stream Routines 


Stream I/O functions handle data as a continuous stream of characters. To 

use the stream functions, you must include the file STDIO.H in your program. 
This file defines constants, types, and structures used in the stream functions, 
and contains function declarations and macro definitions for the stream 
routines. 
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When a file is opened for I/O using the stream functions, the opened file is as- 
sociated with a structure of type FILE (defined in STDIO.H) containing basic in- 
formation about the file. A pointer to the FILE structure is returned when the 
stream is opened. Subsequent operations use this pointer (also called the “stream 
pointer,” or just “stream”’) to refer to the file. 


The stream functions provide for buffered, formatted, or unformatted input and 
output. When a stream is buffered, data that is read from or written to the stream 
is collected in an intermediate storage location called a “buffer”. In write opera- 
tions, the output buffer’s contents are written to the appropriate final location 
when the buffer is full, the stream is closed, or the program terminates normally. . 
The buffer is said to be “flushed” when this occurs. In read operations, a block of 
data is placed in the input buffer read from the buffer; when the input buffer is 
empty, the next block of data is transferred into the buffer. 


Buffering produces efficient I/O because the system can transfer a large block of 
data in a single operation rather than performing an I/O operation each time a 
data item is read from or written to a stream. However, if a program terminates 
abnormally, output buffers may not be flushed, resulting in loss of data. 


Some of the constants defined in STDIO.H may be useful in your program. The 
manifest constant EOF is defined to be the value returned at end-of-file. NULL is 
the null pointer. FILE is the structure that maintains information about a stream. 
BUFSIZ defines the default size of stream buffers, in bytes. 


Routine Use 

clearerr Clears the error indicator for a stream 

fclose Closes a stream | 
fcloseall Closes all open streams 

fdopen Associates a stream with an open file handle 
feof Tests for end-of-file on a stream 

ferror Tests for error on a stream 

fflush Flushes a stream 

fgetc Reads a character from a stream (function version) 
fgetchar Reads a character from stdin (function version) 
fgetpos Gets the position indicator of a stream 

fgets Reads a string from a stream 

fileno Gets the file handle associated with a stream 
flushall Flushes all streams 


fopen Opens a stream 
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fprintf Writes formatted data to a stream 

fputc Writes a character to a stream (function version) 
fputchar Writes a character to stdout (function version) 
fputs Writes a string to a stream 

fread Reads unformatted data from a stream 
freopen Reassigns a FILE pointer to a new file 

fscanf Reads formatted data from a stream 

fseek Moves file position to a given location 
fsetpos Sets the position indicator of a stream 
_fsopen Opens a stream with file sharing 

ftell Gets current file position 

fwrite Writes unformatted data items to a stream 
getc Reads a character from a stream 

getchar Reads a character from stdin 

gets Reads a line from stdin 

getw Reads a binary int item from a stream 

printf Writes formatted data to stdout 

putc Writes a character to a stream 

putchar Writes a character to stdout 

puts Writes a line to a stream 

putw Writes a binary int item to a stream 

rewind « Moves file position to beginning of a stream 
rmtmp Removes temporary files created by tmpfile 
scanf Reads formatted data from stdin 

setbuf Controls stream buffering 

setvbuf Controls stream buffering and buffer size 
sprintf Writes formatted data to a string 

sscanf Reads formatted data from a string 

tempnam Generates a temporary file name in given directory 
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tmpfile Creates a temporary file 
tmpnam Generates a temporary file name 
ungetc Places a character in the buffer 
vfprintf Writes formatted data to a stream 
vprintf Writes formatted data to stdout 
vsprintf Writes formatted data to a string 


2.7.2.1 Opening a Stream 


A stream must be opened using the fdopen, fopen, freopen, or _fsopen function 
before input and output can be performed on that stream. When opening a 
stream, the named stream can be opened for reading, writing, or both, and can be 
opened in either text or binary mode. 


The fdopen, fopen, freopen, and _fsopen functions return a FILE pointer. You 
normally assign the pointer value to a variable and use the variable to refer to the 
opened stream. For instance, if your program contains the lines 


FILE *infile 
infile = fopen ("test.dat", "r"); 


you can use the FILE pointer variable infile to refer to the stream. 


2.7.2.2 Using Predefined Stream Pointers 


When a program begins execution, the C start-up code automatically opens 
several streams: standard input, standard output, and standard error. By default, 
the standard input, standard output, and standard error streams are directed to the 
console (keyboard and screen). This means that when a program expects input 
from the “standard input,” it receives that input from the console. Similarly, a 
program that writes to the “standard output” prints its data to the console. Error 
messages generated by the library routines are sent to the “standard error,” mean- 
ing that error messages appear on the user’s console. 


Under DOS, two additional streams are opened: standard auxiliary and standard 
print. (These streams are not available in OS/2.) The assignment of standard 
auxiliary and standard print depends on the machine configuration. These 
streams usually refer to the first serial port and a printer port, but those ports may 
not be available on some systems. Be sure to check your machine configuration 
before using these streams. 


You can refer to the standard streams with the following predefined stream 
pointers: 
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Pointer Stream 

stdin Standard input 

stdout Standard output 

stderr Standard error 

stdaux . Standard auxiliary (DOS only) 
stdprn Standard print (DOS only) 


You can use these pointers in any function that requires a stream pointer as an ar- 
gument. Some functions, such as getchar and putchar, are designed to use stdin 
or stdout automatically. The pointers stdin, stdout, stderr, stdaux, and stdprn 

are constants, not variables; do not try to assign them a new stream pointer value. 


DOS and OS/2 allow you to redirect a program’s standard input and standard out- 
put at the operating-system command level. OS/2 also allows you to redirect a 
program’s standard error. See your operating system user’s manual for a com- 
plete discussion of redirection. 


Within your program, you can use freopen to redirect stdin, stdout, stderr, 
stdaux, or stdprn so that it refers to a disk file or to a device. See the reference 
description of freopen for more details. 


2.7.2.3 Controlling Stream Buffering 


As mentioned earlier, stream routines can use in-memory buffers to speed I/O 
operations. Files opened using the stream routines are buffered by default, except 
for stdaux and stdprn, which are normally unbuffered. The stdout and stderr 
streams are flushed whenever they are full or (if you are writing to a character 
device) after each library call. . 


By using the setbuf or setvbuf function, you can cause a stream to be unbuff- 
ered, or you can associate a buffer with an unbuffered stream. Buffers allocated 
by the system are not accessible to you, but buffers allocated with setbuf or 
setvbuf refer to arrays in your program and can be manipulated. Buffers can be 
any size up to 32,767 bytes. This size is set by the manifest constant BUFSIZ in 
STDIO.H if you use seftbuf; if you use setvbuf, you can set the size of the buffer 
yourself. (See the descriptions of setbuf and setvbuf in the reference section for 
more details.) 


NOTE These routines affect only buffers created by C library routines. They have no effect 
on buffers created by the operating system. 
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2.7.2.4 Closing Streams 


The fclose and fcloseall functions close a stream or streams. The fclose routine 
closes a single specified stream; fcloseall closes all open streams except stdin, 
stdout, stderr, stdaux, and stdprn. If your program does not explicitly close a 
stream, the stream is automatically closed when the program terminates. How- 
ever, it is a good practice to close a stream when your program is finished with i it, 
as the number of streams that can be open at a given time is limited. 


2.7.2.5 Reading and Writing Data 


The stream functions allow you to transfer data in a variety of ways. You can 
read and write binary data (a sequence of bytes), or specify reading and writing 
by characters, lines, or more complicated formats. 


Reading and writing operations on streams always begin at the current position 
of the stream, known as the “file pointer” for the stream. The file pointer is 
changed to reflect the new position after a read or write operation takes place. 
For example, if you read a single character from a stream, the file pointer is in- 
creased by one byte so that the next operation begins with the first unread char- 
acter. If a stream is opened for appending, the file pointer is automatically 
positioned at the end of the file before each write operation. 


The fseek and fsetpos functions allow you to position the file pointer anywhere 
in a file. The next operation occurs at the position you specified. The rewind 
routine positions the file pointer at the beginning of the file. Use the ftell or 
fgetpos routine to determine the current position of the file pointer. 


The feof macro detects an end-of-file condition on a stream. Once the end-of-file 
indicator is set, it remains set until the file is closed, or until clearerr, fseek, 
fsetpos, or rewind is called. 


Streams associated with a character-oriented device (such as a console) do not 
have file pointers. Data coming from or going to a console cannot be accessed 
randomly. Routines that set or get the file-pointer position (such as fseek, 
fgetpos, fsetpos, ftell, or rewind) have undefined results if used on a stream as- 
sociated with a character-oriented device. 


2.1.2.6 Detecting Errors 


When an error occurs in a stream operation, an error indicator for the stream is 
set. You can use the ferror macro to test the error indicator and determine 
whether an error has occurred. Once an error has occurred, the error indicator for 
the stream remains set until the stream is closed, or until you explicitly clear the 
error indicator by calling clearerr or rewind. 
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2./.3 Low-Level Routines 


Low-level input and output calls do not buffer or format data. Declarations 

for the low-level functions are given in the include files IO.H, FCNTL.H, 
SYS\TYPES.H, and SYS\STAT.H. Unlike the stream-functions, low-level func- 
tions do not require the include file STDIO.H. However, some common con- 
stants are defined in STDIO.H; for example, the end-of-file indicator (EOF) may 
be useful. If your program requires these constants, you must include STDIO.H. 


close Closes a file 

creat Creates a file 

dup Creates a second handle for a file 
dup2 Reassigns a handle to a file 

eof Tests for end-of-file 

Iseek Repositions file pointer to a given location 
open Opens a file 

read Reads data from a file 

sopen Opens a file for file sharing 

tell Gets current file-pointer position 
umask Sets default file-permission mask 
write Writes data to a file 


2.7.3.1 Opening a File 


You must open a file before performing I/O functions on it. The open function 
opens a file; it can also create the file when opening it. In OS/2 and DOS ver- 
sions 3.0 and later, you can use sopen to open a file with file-sharing attributes. 
The creat function can create and open a file. 


The file can be opened for reading, writing, or both, and opened in either text or 
binary mode (see Section 2.7.1, “Text and Binary Modes”). The include file 
FCNTL.H must be included when opening a file, as it contains definitions for 
flags used in open. In some cases, the files SYS\TYPES.H and SYS\STAT.H 
must also be included; for more information, see the reference description for the 
open function. 


These functions return a file handle, which is normally assigned to an integer 
variable. You use the variable to refer to the opened file. 
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2.7.3.2 Reading and Writing Data 


Use the read and write routines to read and write to files. These operations begin 
at the current position in the file. The current position is updated each time a read 
or write operation occurs. 


The Iseek function allows you to place the file pointer anywhere in the file. The 
next operation occurs at the position you specified. The tell function indicates the 
current position of the file pointer. The eof routine tests for the end of the file. 


Low-level I/O routines set the errno variable when an error occurs. Chapter 3, 
“Global Variables and Standard Types,” describes errno. 


Character-oriented devices, such as the console, do not have file pointers. The 
Iseek and tell routines have undefined results if used on a handle associated with 
a device. 


2.7.3.3 Closing Files 


The close function closes an open file. Open files are automatically closed when 
a program terminates. However, it is a good practice to close a file when your 
program is finished with it, as there is a limit to the number of files that can be 
open at one time. 


2.7.3.4 Using Predefined Handles 


When a program begins execution, three files are automatically opened: standard 
input, standard output, and standard error. In DOS, two additional files are 
opened: standard auxiliary and standard print. (These files are not available in 

— OS/2.) . 


Low-level routines can access these files using the following predefined handles: 


stdin 0 
stdout 1 
stderr 2 
stdaux (DOS only) 3 
stdprn (DOS only) 4 


You can use these file handles without previously opening the files. The files are 
opened and the handles are assigned when the program starts. 


The dup and dup2 functions allow you to assign multiple handles for the same 
file. These functions are typically used to associate the predefined file handles 
with different files. 
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In DOS and OS/2, you can redirect the standard input and standard output at the 
operating-system command level. OS/2 also allows you to redirect the standard 
error. See your operating system user’s manual for a complete discussion of 
redirection. 


2.7.4 Console and Port 1/0 


The console and port I/O routines are implemented as functions and are declared 
in the include file CONIO.H. These functions perform reading and writing opera- 
tions on your console or on the specified port. The cgets, cscanf, getch, getche, 
and kbhit routines take input from the console, while cprintf, cputs, putch, and 
ungetch write to the console. The input or output of these functions can be 


redirected. 

cgets Reads a string from the console 

cprintf Writes formatted data to the console 

cputs . Writes a string to the console 

cscanf Reads formatted data from the console 

getch Reads a character from the console 

getche | Reads a character from the console and echoes it 
inp Reads one byte from the specified I/O port 

inpw Reads a two-byte word from the specified I/O port 
kbhit Checks for a keystroke at the console 

outp Writes one byte to the specified I/O port 

outpw Writes a two-byte word to the specified I/O port 
putch Writes a character to the console 

ungetch “Ungets” the last character read from the console so 


that it becomes the next character read 


NOTE Programs that need only run under DOS can also use a number of direct DOS 1/0 
system calls (_dos_open, _dos_read, _dos_close, etc.) These are described in detail in 
Section 2.14, “System Calls.” 


_ The console or port does not have to be opened or closed before I/O is per- 
formed, so there are no open or close routines in this category. The port I/O 
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routines inp and outp read or write one byte at a time from the specified port. 
The inpw and outpw routines read and write two-byte words, respectively. 


The console I/O routines allow reading and writing of strings (cgets and cputs), 
formatted data (cscanf and cprintf), and characters. Several options are available 
when reading and writing characters. 


The putch routine writes a single character to the console. The getch and getche 
routines read a single character from the console; getche echoes the character 
back to the console, while getch does not. The ungetch routine “ungets” the last 
character read; the next read operation on the console begins with the “ungotten” 
character. 


The kbhit routine determines whether a key has been struck at the console. This 
routine allows you to test for keyboard input before you attempt to read from the 
console. 


NOTE The console I/0 routines are not compatible with stream or low-level library 
routines and should not be used with them. 


2.8 Internationalization 


2.9 Math 


Internationalization routines are useful for creating different versions of a pro- 
gram for international markets. These routines are declared in the header file 
LOCALE.H, except for strftime, which is declared in TIME.H. 


Routine Use 

localeconv Sets a structure with appropriate values for format- 
ting numeric quantities 

setlocale Selects the appropriate locale for the program 

strcoll Compares strings using locale-specific information 

strftime Formats a date and time string 

strxfrm Transforms a string based on locale-specific 
information 


The math routines allow you to perform common mathematical calculations. All 
math routines work with floating-point values and therefore require floating- 
point support (see Section 1.8, “Floating-Point Support”). 
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The math library provides two versions of some routines. The first version of the 
routine supports double arguments and return values. The second version sup- 
ports an 80-bit data type, allowing the routine to take long double arguments and 
return a long double value. The second version usually has the same name with 
the suffix I. For instance, the acos routine supports double arguments and return 
values, while acosl supports long double arguments and return values. 


Routines which support long double values are not available when you compile 
with the /Fpa (alternate math) compiler option. The same is true of the _clear 87, 
_control87, and _status87 routines. 


Most math declarations are in the include file MATH.H. However, the _clear87, 
_control87, fpreset, and _status87 routines are defined in FLOAT.H, the abs 
and labs functions are defined in MATH.H and STDLIB.H, and the div and Idiv 

routines are declared i in STDLIB.H. 


Routine 
acos, acosl 
asin, asinl 
atan, atanl 
atan2, atan21 
bessel 

cabs, cabsl 


ceil, ceill 


Use 

Calculate the arccosine 

Calculate the arcsine 

Calculate the arctangent 

Calculate the arctangent 

Calculates Bessel functions 

Find the absolute value of a complex number 


Find the integer ceiling 


_Cclear87 Gets and clears the floating-point status word 

_control87 Gets the old floating-point control word and sets a 
new control-word value 

cos, cosl Calculate the cosine 

cosh, coshli Calculate the hyperbolic cosine 

dieeetomsbin Converts IEEE double-precision number to Micro- 
soft (MS) binary format 

div Divides one integer by another, returning the 
quotient and remainder 

dmsbintoieee Converts Microsoft binary double-precision number 
to IEEE format 

exp, expl Calculate the exponential function 

fabs, fabsl Find the absolute value 
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fieeetomsbin 
floor, floor] 


fmod, fmodl 


fmsbintoieee 


_fpreset 
frexp, frexpl 
hypot, hypotl 
Idexp, Idexpl 
Idiv 


log, logl 
log10, logi01 


_Irotl, _lrotr 


matherr, _matherrl 
max, min 


modf, modfl 


pow, powl 
rand 


_rotl, _rotr 


sin, sinl 
sinh, sinhl 
sqrt, sqrtl 
srand 
_status87 
tan, tanl 


tanh, tanhl 


Converts IEEE single-precision number to Microsoft 
binary format 


Find the largest integer less than or equal to the 
argument 


Find the floating-point remainder 


Converts Microsoft binary single-precision number 
to IEEE format 


Reinitializes the floating-point-math package 
Calculate an exponential value 

Calculate the hypotenuse of right triangle 
Calculate the product of the argument and 2°? 


Divides one long integer by another, returning the 
quotient and remainder 


Calculate the natural logarithm 
Calculate the base-10 logarithm 


Shift an unsigned long int item left (_Irotl) or right 
(_Irotr) 


Handle math errors 
Return the larger or smaller of two values 


Break down the argument into integer and fractional 
parts 


Calculate a value raised to a power 
Gets a pseudorandom number 


Shift an unsigned int item left (_roftl) or right 
(_rotr) 


Calculate the sine 

Calculate the hyperbolic sine 

Find the square root 

Initializes a pseudorandom series 
Gets the floating-point status word 
Calculate the tangent 


Calculate the hyperbolic tangent 


48 Microsoft C Run-Time Library Reference 
Ti FT Ne i a a EE oe 8 


The bessel routine does not correspond to a single function, but to twelve func- 
tions named jo, jl, jn, yO, yl, yn, _jOl, jll, _jnl, _yOl, yl, and _ynl. 


The matherr and _matherrl routines are invoked by the math functions when er- 
rors occur. The matherr routine handles functions that return a double value and 
_matherrl handles routines that return a long double. 


These routines are defined in the library, but you can redefine them for different 
error-handling. The user-defined function, if given, must follow the rules given 
in the reference description of matherr and _matherrl. 


You are not required to supply a definition for the matherr routines. If no defini- 
tion is present, the default error returns for each routine are used. The reference 
description of each routine describes that routine’s error returns. 


2.10 Memory Allocation 


The memory-allocation routines allow you to allocate, free, and reallocate blocks 
of memory. Memory-allocation routines are declared in the include file 


MALLOC.H. 
Routine 


alloca 


_bfreeseg 
_bheapseg 
calloc, _bcalloc, _fcalloc, _ncalloc 


_expand, _bexpand, _fexpand, 
_nexpand 


free, bfree, ffree, _nfree 


_freect 


halloc 
_heapadd, _bheapadd 


_heapchk, _bheapchk, _fheapchk, 
_nheapchk 


_heapmin, _bheapmin, 
_fheapmin, _nheapmin 


= 


Allocates a block of memory from 
the program’s stack 


Frees a based heap 
Allocates a based heap 
Allocate storage for an array 


Expand or shrink a block of memory 
without moving its location 


Free an allocated block 


Returns approximate number of items 
of given size that could be allocated 
in the near heap 


Allocates storage for huge array 
Add memory to a heap 


Check a heap for consistency 


Release unused memory in a heap 
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_heapset, _bheapset, _fheapset, Fill free heap entries with a specified 

_nheapset value 

_heapwalk, _bheapwalk, Return information about each entry 

_fheapwalk, nheapwalk in a heap 

hfree Frees a block allocated by halloc 

malloc, _bmalloc, _fmalloc, Allocate a block of memory 

_nmalloc 

_memavl Returns approximate number of bytes 
available for allocation in the near 
heap 

_memmax Returns size of largest contiguous 
free block in the near heap 

_msize, _bmsize, _fmsize, Return size of an allocated block 

_nmsize 

realloc, _brealloc, _frealloc, Reallocate a block to a new size. 

_nrealloc 

stackavail Returns size of stack space available 


for allocation with alloca 


Some memory-management routines, such as malloc, are available in different 
versions that begin with _b, _f, or _n. These variations are described in the fol- 
lowing section. 


The malloc and free routines allocate and free memory space, respectively, 
while a program runs. The malloc routine allocates memory from the “heap,” 
which is a pool of memory not otherwise used by your program. In tiny-, small-, 
and medium-model programs, the heap consists of unused memory in your pro- 
gram’s default data segment. In compact-, large-, and huge-model programs, it is 
unused memory outside the default data segment. 


The malloc and free routines satisfy the memory-allocation requirements of most 
programs. More specialized memory-management routines are discussed below. 


The realloc and _expand routines can expand or shrink an allocated memory 
block. They behave differently in cases in which there is not enough room to ex- 
pand the block in its current location. In this case, realloc moves the block as 
needed, but expand does not. 


The calloc routine allocates memory for an array and initializes every byte in the 
allocated block to 0. 


The halloc routine is similar to calloc, except that it can allocate memory for a 
huge array (one that exceeds 64K in size). This routine is useful when you need a 
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very large data object, or if you need to return allocated memory to the operating 
~ system for subsequent calls to the spawn family of functions. 


2.10.1 Near and Far Heaps 


As mentioned in the previous section, heap memory can reside inside or outside 
your program’s default data segment, depending on what memory model your 
program uses. When it lies inside the default data segment, the heap is called the 
“near heap,” since it can be accessed with near pointers. The “far heap” is 
memory that spans one or more segments outside the default data segment. The 
far heap can be accessed only with far pointers. 


In various memory models, malloc automatically allocates memory from the 
near heap or far heap, as appropriate. The C library also includes near and far ver- 
sions of malloc, free, and other memory-management routines, which allow you 
to specify the near and far heaps explicitly. These have the same names as stand- 
ard memory routines, but are preceded by _n (for near) or _f (for far). 


For instance, the _nmalloc routine always allocates memory from the near heap 
and returns a near pointer, no matter which memory model your program uses. 
Use _nfree to release memory allocated with _nmalloc. 


Similarly, _fmalloc always allocates memory from the far heap and returns a far 
pointer, regardless of memory model. Use the _ffree routine to release memory 
allocated with _fmalloc. 


2.10.2 Based Heaps 


You can also allocate memory from a “based heap,” which is a single segment 
that lies outside the default data segment. Based-heap routines generally use the 
same names as standard memory routines, but begin with _b. For instance, 
_bmalloc allocates a memory block from the based heap and _bfree frees the 
block. 


Based heaps offer the following advantages: 


a Localized data. Based heaps allow you to group related data in a single seg- 
ment. This can simplify the management of related data. In OS/2, based heaps 
can also minimize the risk of general protection faults and improve 
performance. 


m= Faster pointer arithmetic. Although the based heap lies in the far data seg- 
ment, pointers to its data items are the same size as near pointers. Thus, 
pointer arithmetic on items in a based heap is faster than pointer arithmetic on 
items in the far heap. 


The _bheapseg routine allocates a based heap segment, from which you can then 
allocate blocks of memory. You can call _bheapseg more than once to allocate 
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as many based-heap segments as needed (within the confines of available 
memory). 


The _bfreeseg routine frees a based-heap segment. This routine frees every block 
in the based-heap segment, whether or not you previously freed the blocks 
individually. 


NOTE Near-, far-, and based-heap calls are not ANSI compatible and will make your pro- 
gram less portable. 


2.11 Process and Environment Control 


The process-control routines allow you to start, stop, and manage processes from 
within a program. Environment-control routines allow you to get and change in- 
formation about the operating-system environment. 


A “process” is a program being executed by the operating system. It consists of 
the program’s code and data, plus information about the process, such as the num- 
ber of open files. Whenever you execute a program at the operating-system level, 
you start a process. 


All process-control functions except signal are declared in the include file 
PROCESS.H. The signal function is declared in SIGNAL.H. The abort, exit, 
and system functions are also declared in the STDLIB.H include file. The 
environment-control routines (getenv and puteny) are declared in STDLIB.H. 


Routine Use 

abort Aborts a process without flushing buffers or calling 
functions registered by atexit and onexit 

assert Tests for logic error 

atexit Schedules routines for execution at program 
termination 

_beginthread Creates an execution thread (OS/2 only) 

_cexit Performs the exit termination procedures (such as 
flushing buffers) and returns control to the calling 
program 

_¢ exit Performs the _exit termination procedures and re- 


turns control to the calling program 


cwait . Suspends the calling process until a specified child 
process terminates (OS/2 only) 


_endthread Terminates an execution thread (OS/2 only) 


52 Microsoft C Run-Time Library Reference 


execl Executes child process with argument list 

execle Executes child process with argument list and given 
environment 

execlp Executes child process using PATH variable and ar- 
gument list 

execlpe Executes child process using PATH variable, given 
environment, and argument list | 

execv Executes child process with argument array 

execve Executes child process with argument array and 
given environment 

execvp Executes child process using PATH variable and ar- 
gument array 

execvpe Executes child process using PATH variable, given 


environment, and argument array 


exit Calls functions registered by atexit and onexit, then 
flushes all buffers and closes all open files before ter- 
minating the process 


_exit Terminates process without processing atexit or 
onexit functions or flushing buffers 

getenv Gets the value of an environment variable 

getpid Gets process ID number 

longjmp Restores a saved stack environment 

onexit Schedules routines for execution at program 

. termination 

_pclose Waits for a child command and closes a pipe on the 
associated stream 

perror Prints error message 

_pipe Creates a pipe 

_ _popen Creates a pipe and asynchronously executes a child 

copy of the command processor 

putenv Adds or changes the value of an environment 
variable 

raise Sends a signal to the calling process 


setjmp Saves a stack environment 
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signal Handles an interrupt signal 

spawnl Executes child process with argument list 

spawnle Executes child process with argument list and given 
environment 

spawnlp Executes child process using PATH variable and ar- 
gument list 

spawnlpe Executes child process using PATH variable, given 
environment, and argument list 

spawnv Executes child process with argument array 

spawnve Executes child process with argument array and 
given environment 

spawnvp Executes child process using PATH variable and ar- 
gument array 

spawnvpe Executes child process using PATH variable, given 
environment, and argument array 

system Executes an operating system command 

wait Suspends the calling process until any of the caller’s 


immediate child processes terminate (OS/2 only) 


The atexit and onexit routines create a list of functions to be executed when the 
calling program terminates. The only difference between the two is that atexit is 
part of the ANSI standard. The onexit function is offered for compatibility with 
previous versions of Microsoft C. 


The _exit routine terminates a process immediately, whereas exit terminates the 
process only after flushing buffers and calling any functions previously regis- 
tered by atexit and onexit. The _cexit and _c_exit routines are identical to exit 
and _exit, respectively, except that they return control to the calling program 
without terminating the process. 


The setjmp and longjmp routines save and restore a stack environment. These 
allow you to execute a nonlocal goto. 


The exec and spawn routines start a new process called the “child” process. The 
difference between the exec and spawn routines is that the spawn routines are 
capable of returning control from the child process to its caller (the “parent” - 
process). Both the parent process and the child process are present in memory 
(unless P_ OVERLAY is specified). In the exec routines, the child process over- 
lays the parent process, so returning control to the parent process is impossible 
(unless an error occurs when attempting to start execution of the child process). 
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There are eight forms each of the spawn and exec routines (see Table 2.1). The 
differences among the forms involve the method of locating the file to be ex- 
ecuted as the child process, the method for passing arguments to the child 
process, and the method of setting the environment. 


Passing an argument list means that the arguments to the child process are listed 
separately in the exec or spawn call. Passing an argument array means that the ar- 
guments are stored in an array, and a pointer to the array is passed to the child 
process. The argument-list method is typically used when the number of argu- 
ments is constant or is known at compile time. The argument-array method is use- 
ful when the number of arguments must be determined at run time. 


Several process-control routines take advantage of the multitasking capability of 
OS/2. The _beginthread and _endthread routines create and terminate execu- 
tion threads. The cwait and wait routines suspend the calling process until one 
child process terminates. The pipe, popen, and _pclose routines create and 
manipulate pipes, which link processes for sequential execution. 


Table 2.1. Forms of the spawn and exec Routines 


Argument-Passing 


Routines Locating the File Convention Environment Settings 
execl, spawnl Do not use PATH Argument list Inherited from parent 
execle, spawnle Do not use PATH Argument list Pointer to environ- 


ment table for child 
process passed as last 


argument 
execlp, spawnlp Use PATH Argument list Inherited from parent 
execlpe, spawnlpe Use PATH Argument list Pointer to environ- 


ment table for child 
process passed as last 


argument 
execv, Spawnv Do not use PATH . Argument array Inherited from parent 
execve, Spawnve Do not use PATH Argument array Pointer to environ- 
ment table for child 
process passed as last 
argument 
execvp, spawnvp Use PATH Argument array Inherited from parent 
execvpe, spawnvpe Use PATH Argument array Pointer to environ- 


ment table for child 
process passed as last 
argument 
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The assert macro is typically used to test for logic errors. It prints a message 
when a given “assertion” fails to hold true. Defining the identifier NDEBUG to 
any value causes occurrences of assert to be removed from the source file, thus 
allowing you to turn off assertion checking without modifying the source file. 


2.12 Searching and Sorting 


Search and sort routines provide binary-search, linear-search, and quick-sort 
capabilities. They are all declared in SEARCH.H. 


Routine 
bsearch 
Ifind 


Isearch 


qsort 


2.13 String Manipulation 


Use 
Performs binary search 
Performs linear search for given value 


Performs linear search for given value, which is 
added to array if not found 


Performs quick sort 


The string functions are declared in the include file STRING.H. They allow you 
to compare strings, copy them, search for strings and characters, and perform 


various other operations. 


Routines beginning with _f are model-independent versions of the corresponding 
routines and are useful in mixed-model programs. These routines can be called 
from any point in the program, regardless of which model is being used. 


streat, _fstrcat 
strchr, _fstrchr 
stremp, _fstremp 
strepy, _fstrepy 


strespn, _fstrespn 


strdup, _fstrdup, 
_hstrdup 


strerror 


Use 

Append one string to another 

Find first occurrence of a given character in a string 
Compare two strings 

Copy one string to another 


Find first occurrence of a character from a given 
character set in a string 


Duplicate a string 


Maps an error number to a message string 
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_Strerror 

stricmp, _fstricmp 
strlen, _fstrlen 
striwr, _fstriwr 
strncat, _fstrncat 
strncmp, _fstrncmp 
strncpy, _fstrncpy 


strnicmp, _fstrnicmp 


strnset, _fstrnset 


strpbrk, _fstrpbrk 


strrehr, _fstrrchr 
strrev, _fstrrev 
strset, _fstrset 


strspn, _fstrspn 
strstr, _fstrstr 


strtok, _fstrtok 


strupr, _fstrupr 


Maps a user-defined error message to a string 
Compare two strings without regard to case 
Find length of string 

Convert string to lowercase 


Append characters of a string 


Compare characters of two strings 


Copy characters of one string to another 


Compare characters of two strings without regard 
to case 


Set characters of a string to a given character 


Find first occurrence of a character from one string 
in another 


Find last occurrence of a given character in string 
Reverse string 
Set all characters of a string to a given character 


Find first substring from a given character set ina 
string 


Find first occurrence of a given string in another 
string | 


Find next token in a string 


Convert a string to uppercase 


All string functions work on null-terminated character strings. When working 
with character arrays that do not end with a null character, you can use the buffer- 
manipulation routines, described in Section 2.1. 


2.14 System Calls 


The following routines give access to IBM-PC BIOS interrupts and DOS system 
calls. Except for the FP_OFF, FP_SEG, and segread routines, these routines are 
for DOS application programs only; they do not work under OS/2. 
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2.14.1 BIOS Interface 


The functions in this category provide direct access to the BIOS interrupt ser- 
vices. They are all declared in BIOS.H. 


Routine 


_bios_disk 


_bios_equiplist 
_bios_keybrd 


_bios_memsize 


_bios_printer 


_bios_serialcom 


_bios_timeofday 


Use 


Issues service requests for both hard and floppy 
disks, using INT 0x13 


Performs an equipment check, using INT Ox11 


Provides access to keyboard services, using 
INT 0x16 


Obtains information about available memory, using 
INT 0x12 


Performs printer output services, using INT 0x17 


Performs serial communications tasks, using 
INT 0x14 


Provides access to system clock, using INT Ox1A 


NOTE BIOS routines are hardware dependent. Some of them may not work as expected 
~ on machines whose hardware differs from the IBM PC. 


2.14.2 DOS Interface 


These routines are implemented as functions and declared in DOS.H. 


Routine 


bdos 


_chain_intr 
_disable 


_dos_allocmem 


_dos_close 


_dos_creat 


Use 


Invokes DOS system call; uses only DX and AL 
registers 


Chains one interrupt handler to another 
Disables interrupts 


Allocates a block of memory, using DOS system 
call 0x48 


Closes a file, using DOS system call 0x3E 


Creates a new file and erases any existing file 
having the same name, using DOS system call 0x3C 
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_dos_creatnew 


_dos_findfirst 
_dos_findnext 
_dos_freemem 


_dos_getdate 
_dos_getdiskfree 


_dos_getdrive 
_dos_getfileattr 
_dos_getftime 
_dos_gettime 
_dos_getvect 
_dos_keep 


_dos_open 
_dos_read 


_dos_setblock 
_dos_setdate 
_dos_setdrive 
_dos _setfileattr 


_dos_setftime 


Creates a new file and returns an error if a file 
having the same name exists, using DOS system 
call 0x5B 


Finds first occurrence of a given file, using DOS sys- 
tem call Ox4E 


Finds subsequent occurrences of a ata file, using 
DOS system call Ox4F 


Frees a block of memory, using DOS system 
call 0x49 


Gets the system date, using DOS system call 0x2A 


Gets information on a disk volume, using DOS sys- 
tem call 0x36 


Gets the current default drive, using DOS system 
call 0x19 


Gets current attributes of a file or directory, using 
DOS system call 0x43 


Gets the date and time a file was last written, using 
DOS system call 0x57 


Gets the current system time, using DOS system 
call 0x2C 


Gets the current value of a specified interrupt vector, 
using DOS system call 0x35 


Installs terminate-and-stay-resident (TSR) programs 
using DOS system call 0x31 


Opens an existing file, using DOS system call Ox3D 
Reads a file, using DOS system call 0x3F 


Changes the size of a previously allocated block, 
using DOS system call 0x4A 


Sets the current system date, using DOS system 
call 0x2B 


Sets the default disk drive, using DOS system 
call OxOE 


Sets the current attributes of a file, using DOS sys- 
tem call 0x43 


Sets the date and time that the specified file was last 
written, using DOS system call 0x57 


_dos_settime 


_dos_setvect 


_dos_write 


dosexterr 


_enable 


FP_OFF 
FP_SEG 


_harderr 
_hardresume 
_hardretn 
int86 

int86x 


intdos 
intdosx 


segread 
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Sets the system time, using DOS system call 0x2D 


Sets a new value for the specified interrupt vector, 
using DOS system call 0x25 


Sends output to a file, using DOS system call 0x40 


Obtains in-depth error information from DOS sys- 
tem call 0x59 


Enables interrupts 


Returns offset portion of a far pointer (OS/2 
and DOS) 


Returns segment portion of a far pointer (OS/2 
and DOS) 


Establishes a hardware error handler 

Returns to DOS after a hardware error 

Returns to the application after a hardware error 
Invokes DOS interrupts 

Invokes DOS interrupts with segment register values 


Invokes DOS system call using registers other than 
DX and AL 


Invokes DOS system call using registers other than 
DX and AL with segment register values 


Returns current values of segment registers (OS/2 
and DOS) 


The _harderr routine is used to define a hardware-error interrupt handler. The 
_hardresume and _hardretn routines are used within a hardware error handler 
to define the return from the error. 


The dosexterr function obtains and stores the error information returned by DOS 
system call 0x59 (extended error handling). This function is provided for use 
with DOS versions 3.0 and later. 


The bdos routine is useful for invoking DOS calls that use either or both of the 
DX (DH/DL) and AL registers for arguments. However, bdos should not be used 
to invoke system calls that return an error code in AX if the carry flag is set; - 
since your program cannot detect whether the carry flag is set, it cannot deter- 
mine whether the value in AX is a legitimate value or an error value. In this case, 
the intdos routine should be used instead, since it allows the program to detect 
whether the carry flag is set. The intdos routine can also be used to invoke DOS 
calls that use registers other than DX and AL. 
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2.15 Time 


The intdosx routine is similar to the intdos routine, but is used when ES is re- 
quired by the system call, when DS must contain a value other than the default 
data segment (for instance, when a far pointer is used), or when making the sys- 
tem call in a large-model program. When calling intdosx, give an meument that 
specifies the segment values to be used in the call. 


The int86 routine can be used to invoke any interrupt. The int86x routine is simi- 
lar; however, like the intdosx routine, it is designed to work with large-model 
programs and far items, as described in the preceding paragraph. 


~ The FP_OFF and FP_SEG routines allow easy access to the segment and offset 


portions of a far pointer value. FP_OFF and FP_SEG are implemented as macros 
and defined in DOS.H. You can use these macros in OS/2 as well as DOS. 


The segread routine returns the current values of the segment registers. This 
routine is typically used with the intdosx and int86x routines to obtain the cor- 
rect segment values. 


The _chain_intr routine is useful for chaining interrupt handlers together. The 
_enable routine enables interrupts, while the _ disable routine disables interrupts. 


The routines prefixed with _dos_ are all direct system interfaces that use the sys- 
tem calls noted above. More detailed information on these system calls can be 
found in the MS-DOS Encyclopedia (Duncan, ed.; Redmond, WA: Microsoft 
Press, 1988)or the Programmer’s PC Sourcebook (Hogan; Redmond, WA: 
Microsoft Press, 1988). 


NOTE The DOS interface 1/0 routines are generally incompatible with console, low-level, 
and stream 1/0 routines. Do not mix different types of 1/0 routines in the same source file. 


The time functions allow you to obtain the current time, then convert and store it 
according to your particular needs. The current time is ee taken from the sys- 
tem time. 


Routine Use 

asctime Converts time from type struct tm to a character 
string 

clock Returns the elapsed CPU time for a process 

ctime Converts time from a long integer to a character 


string 
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difftime Computes the difference between two times 

ftime Puts current system time in variable of type 
struct tm 

gmtime Converts time from integer to struct tm 

localtime Converts time from integer to struct tm with local 
correction 

mktime Converts time to a calendar value 

_Strdate Returns the current system date as a string 

strftime Formats a date and time string 

_Strtime Returns the current system time as a string 

time Gets current system time as a long integer 

tzset Sets external time variables from the environment 


time variable 


utime Sets file-modification time 


The time and ftime functions return the current time as the number of seconds 
elapsed since midnight Universal Coordinated Time (UTC) on January 1, 1970. 
This value can be converted, adjusted, and stored in a variety of ways by using 
the asctime, ctime, gmtime, localtime, and mktime functions. The utime func- 

-tion sets the modification time for a specified file, using either the current time or 
a time value stored in a structure. 


The clock function returns the elapsed CPU time for the calling process. 


The ftime function requires two files: SYS\TYPES.H and SYS\TIMEB.H. It is 
declared in SYS\TIMEB.H. The utime function also requires two include files: 
SYS\TYPES.H and SYS\UTIME.H. It is declared in SYS\UTIME.H. The re- 
mainder of the time functions are declared in the include file TIME.H. 


When you want to use ftime or localtime to make adjustments for local time, 
you must define an environment variable named TZ. Section 3.2, which de- 
scribes the global variables daylight, timezone, and tzname, includes a discus- 
sion of the TZ variable. TZ is also described on the tzset reference page in Part 2 
of this book. 


The _strdate and _strtime routines return strings containing the current date and 
time, respectively, in the DOS and OS/2 date and time format rather than in the 
XENIX-style formats. 


The stfrtime function is useful for creating international versions of a program. 
See Section 2.8, “Internationalization.” 
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2.16 Variable-Length Argument Lists 


The va_arg, va_end, and va_start routines are macros that provide a portable 
way to access the arguments to a function when the function takes a variable 
number of arguments. Two versions of the macros are available: the macros de- 
fined in the VARARG.H include file, which are compatible with the UNIX Sys- 
tem V definition, and the macros defined in STDARG.H, which conform to the 


ANSI C standard. 

Routine Use 

va_arg Retrieves argument from list 
va_end Resets pointer 


va_start Sets pointer to beginning of argument list 


For more information on the differences between the two versions and for an ex- 
planation of how to use the macros, see their descriptions in Part 2 of this book. 


Global Variables 
and Standard Types 


CHAPTER 


The Microsoft C Run-Time Library contains definitions for a number of varia- 
bles and standard types used by library routines. You can access these variables 
and types by including in your program the files in which they are declared, or by 
giving appropriate declarations in your program, as shown in the following 
sections. 


3.1 _amblksiz 


The _amblksiz variable controls memory heap granularity. 
It is declared in the MALLOC.H include file as follows: 


extern unsigned int _amblksiz; 


The _amblksiz variable controls the amount of memory used in the heap for dy- 
namic memory allocation. 


Memory space is always requested from the operating system in blocks contain- 
ing _amblksiz bytes. The first time a program calls a memory-allocation func- 
tion such as malloc, the operating system allocates a block of heap memory. The 
size of this block is defined by _amblksiz, which has a default value of 8K 
(8,192 bytes). 


Later memory requests are satisfied from the original block. When that block is 
exhausted, another block of _amblksiz bytes is allocated. If your C program 
allocates a block larger than _amblksiz, multiple blocks that are each of size 
_amblksiz are allocated until the request is satisfied. 


To change the size of the default memory block, assign the desired size to the 
_amblksiz variable, as in the following example: 


_amblksiz = 2048; 
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3.2 daylight, 


The heap allocator always rounds the operating-system request to the nearest 
power of 2 greater than or equal to_amblksiz. The above statement allocates 
memory in multiples of 2K (2,048 bytes). 


Fewer system calls are required if you set _amblksiz to a large value, but your 
program may use more memory than needed. If program speed is important, set 
_amblksiz to a large value. If size is important, set_amblksiz to a smaller value. 


Note that adjusting the value of _amblksiz affects allocation in the near, far, and 
based heaps. The value of _amblksiz has no effect on huge memory blocks 
(those allocated with halloc and similar functions). 


timezone, izname 


The daylight, timezone, and tzname variables are global timezone variables 
used in time functions. 


They are declared in the TIME.H include files as follows: 
extern int daylight; 


extern long timezone; 
extern char *tzname [2]; 


Some time and date routines use the daylight, timezone, and tzname variables 
to make local-time adjustments. Whenever a program calls the ftime, localtime, 
or tzset function, the value of daylight, timezone, and tzname is determined 
from the value of the TZ environment variable. If you do not explicitly set the 
value of TZ, the default value of PST8PDT is used. The following list shows 
each variable and its value: 


Variable Value 

daylight Nonzero if a daylight-saving-time zone (DST) is 
specified in TZ; otherwise zero. Default value is one. 

timezone | Difference in seconds between Greenwich mean 
time and the local time. Default value is 28,800. 

tzname[0] Three-letter time zone name derived from the TZ en- 
vironment variable. Default value is “PST” (Pacific 
standard time). 

tzname[1] Three-letter daylight-saving-time zone name derived 


from the TZ environment variable. Default value is 
PDT. If the DST zone is omitted from TZ, 
tzname[1] is an empty string. 
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3.3 _doserrno, errno, sys_errlist, sys_nerr 


The _doserrno, errno, sys_errlist, and sys_nerr variables contain error codes, 
and are used by the perror and _strerror routines to print error information. 


These variables are declared in the STDLIB.H include file. Manifest constants 
for the errno variables are declared in the ERRNO.H include file. The declara- 
tions are as follows: 


extern int doserrno; 
extern int errno; 

extern char *sys_errlist[ J; 
extern int sys_nerr; 


The errno variable is set to an integer value to reflect the type of error that has 
occurred in a system-level call. Each errno value is associated with an error mes- 
sage, which can be printed with the perror routine or stored in a string with the 
strerror routine. 


Note that only some routines set the errno variable. If a routine sets errno, the 
description of the routine in the reference section says so explicitly. 


The value of errno reflects the error value for the last call that set errno. How- 
ever, this value is not necessarily reset by later successful calls. To avoid confu- 
sion, test for errors immediately after a call. 


The include file ERRNO.H contains the definitions of the errno values. How- 
ever, not all of the definitions given in ERRNO.H are used in DOS and OS/2. 
Some of the values in ERRNO.H are present to maintain compatibility with 
XENIX and UNIX operating systems. 


The errno values in DOS and OS/2 are a subset of the values for errno in 
XENIX systems. Thus, the errno value is not necessarily the same as the actual 
error code returned by a DOS or OS/2 system call. To access the actual DOS and 
OS/2 error code, use the _doserrno variable, which contains this value. 


In general, you should use _doserrno only for error detection in operations in- 
volving input and output, since the errno values for input and output errors have 
DOS and OS/2 error-code equivalents. In other cases, the value of _doserrno is 
undefined. 


The syserrlist variable is an array; the perror and strerror routines use it to 
process error information. The sys_nerr variable tells how many elements the 
sys_errlist array contains. 
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Table 3.1 gives the errno values for DOS and OS/2, the system error message 
for each value, and the value of each constant. Note that only the ERANGE and 
EDOM constants are specified in the ANSI standard. 


Table 3.1 errno Values and Their Meanings 


Constant Meaning Value 
E2BIG Argument list too long 7 
EACCES Permission denied 13 
EBADF Bad file number 9 
EDEADLOCK Resource deadlock would occur 36 
EDOM Math argument 33 
EEXIST File exists 17 
EINVAL Invalid argument 22 
EMFILE Too many open files 24 
ENOENT No such file or directory 2 
ENOEXEC Exec format error 8 
ENOMEM Not enough memory 12 
ENOSPC No space left on device . 28 
ERANGE Result too large 34 
EXDEV Cross-device link 18 


3.4 fmode 


The _fmode variable controls the default file-translation mode. 
It is declared in the STDLIB.H include file as follows: 


_ extern int _fmode; 


By default, the value of _fmode is O_TEXT, causing files to be translated in 
text mode (unless specifically opened or set to binary mode). When _fmode is 
set to O_BINARY, the default mode is binary. You can set _fmode to the flag 
O_BINARY by linking with BINMODE.OBJ or by assigning it the O BINARY 
value. 
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3.5 _osmajor, _osminor, _osmode, _osversion 


The osmajor, osminor, osmode, and _osversion variables specify the ver- 
sion number of the operating system or the current mode of operation. 


They are declared in the STDLIB.H include file as follows: 


extern unsigned char _osmajor; 

_ extern unsigned char _osminor; 
extern unsigned char _osmode; 
extern unsigned char _osversion; 


The osmajor, osminor, and _osversion variables specify the version number 
of DOS or OS/2 currently in use. The _osmajor variable holds the “major” ver- 
sion number and the _osminor variable stores the “minor” version number. 
Thus, under DOS version 3.20, _osmajor is 3 and _osminor is 20. The 
_osversion variable holds both values; its low byte contains the major version 
number and its high byte the minor version number. 


These variables are useful for creating programs that run in different versions of 
DOS and OS/2. For example, you can test the _osmajor variable before making 
a call to sopen; if the major version number is earlier (less) than 3, open should 
be used instead of sopen. 


The _osmode variable indicates whether the program is in OS/2 protected mode 
or in real mode (DOS or OS/2 real mode). An _osmode value of DOS_MODE in- 
dicates real mode operation and a value of OS2_MODE indicates protected 
operation. 


3.6 environ 


The environ variable is a pointer to the strings in the process environment. . 
It is declared in the STDLIB.H include file as follows: 


extern char *environ [ ]; 


The environ variable provides access to memory areas containing process- 
specific information. 
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3./ _psp 


The environ variable is an array of pointers to the strings that constitute the 
process environment. The environment consists of one or more entries of 
the form 


NAME=string 


where NAME is the name of an environment variable and string is the value of 
that variable. The string may be empty. The initial environment settings are taken 
from the operating-system environment at the time of program execution. 


The getenv and putenv routines use the environ variable to access and modify 
the environment table. When putenv is called to add or delete environment set- 
tings, the environment table changes size; its location in memory may also 
change, depending on the program’s memory requirements. The environ varia- 
ble is adjusted in these cases and always points to the correct table location. 


The _psp variable contains the segment address of the program segment prefix 
(PSP) for the process. 


It is declared in the STDLIB.H include file as follows: 
extern unsigned int _psp; 


The PSP contains execution information about the process, such as a copy of the 
command line that invoked the process and the return address on process termina- 
tion or interrupt. The _ psp variable can be used to form a long pointer to the 

PSP, where _psp is the segment value and 0 is the offset value. 


Note that the _psp variable is supported only in DOS. 


3.8 Standard Types 


A number of library routines use values whose types are defined in include files. 
In the following list, these types are described, and the include file defining each 
type is given. 


Standard Type Description 


clock _t The clock_t type, defined in TIME.H, stores time 
values. It is used by the clock function. 


complex The complex structure, defined in MATH.H, stores 
the real and imaginary parts of complex numbers. It 
is used by the cabs function. 
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diskfree_t 


diskinfo_t 


div_t, Idiv t 


dosdate_t 


dostime_t 


DOSERROR 


exception 


FILE 


find_t 


fpos t 


jmp_buf 


Iconv 


The diskfree_t structure, defined in DOS.H, stores 
disk information used by the _dos_getdiskfree 
routine. 


The diskinfo_t structure, defined in BIOS.H, re- 
cords information about disk drives returned by the 
_bios_disk routine. 


The div_t and Idiv_t structures, defined in 
STDLIB.H, store the values returned by the div and 
Idiv functions, respectively. 


The dosdate_t structure, defined in DOS.H, records 
the current system date used in the _dos_getdate 
and dos _setdate routines. 


The dostime_t structure, defined in DOS.H, records 
the current system time used in the _dos_gettime 
and _dos _settime routines. 


The DOSERROR structure, defined in DOS.H, 
stores values returned by DOS system call 59H 
(available under DOS versions 3.0 and later). 


The exception structure, defined in MATH.H, stores 
error information for math routines. It is used by the 
matherr routine. 


The FILE structure, defined in STDIO.H, is the 
structure used in all stream input and output opera- 
tions. The fields of the FILE structure store informa- 
tion about the current state of the stream. 


The find_t structure, defined in DOS.H, stores file- 
attribute information returned by the _dos_findfirst 
and _dos_findnext routines. 


The fgetpos and fsetpos functions use the fpos_t ob- 
ject type, defined in STDIO.H, to record all the infor- 
mation necessary to uniquely specify every position 
within the file. 


The jmp_buf type, defined in SETJMP.H, is an 
array type rather than a structure type. A buffer of 
this type is used by the setjmp and longjmp 
routines to save and restore the program 
environment. 


The Iconv type is a structure containing formatting 
rules for numeric values in different countries. It is 
defined in LOCALE.H. 
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onexit_t The onexit routine is declared as an onexit_t pointer 
type, which is defined in STDLIB.H. 

ptrdiff_t The ptrdiff_t type is used for the signed integral re- 
sult of the subtraction of two pointers. 

REGS The REGS union, defined in DOS.H, stores byte and 


word register values to be passed to and returned 
from calls to the DOS interface functions. 


sig_atomic_t The sig_atomic_t type, defined in SIGNAL.H, is the 
integral type of an object that can be modified as an 
atomic entity, even in the presence of asynchronous 
interrupts. It is used in conjunction with the signal 


routine. 

size_t The size_t type, defined in STDDEF.H and several 
other include files, is the unsigned integral result of 
the sizeof operator. 

SREGS The SREGS structure, defined in DOS.H, stores the 


values of the ES, CS, SS, and DS registers. This 
structure is used by the DOS interface functions that 
require segment register values (int86x, intdosx, 
and segread). 


stat The stat structure, defined in SYS\STAT.H, con- 
tains file-status information returned by the stat and 
fstat routines. 


time_t The time_t type, defined in TIME.H, represents 
time values in the mktime and time routines. 


timeb The timeb structure, defined in SYS\TIMEB.H, is 
used by the ftime routine to store the current system 
time. 


tm The tm structure, defined in TIME.H, is used by the 
asctime, gmtime, and localtime functions to store 
and retrieve time information. 


utimbuf The utimbuf structure, defined in SYS\UTIME.H, 
stores file access and modification times used by the 
utime function to change file-modification dates. 


va_list The va_list array type, defined in STDARG.H, is 
used to hold information needed by the va_arg 
macro and the va_end routine. The called function 
declares a variable of type va_list, which may be 
passed as an argument to another function. 
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Run-Time Functions 


The second part of this book is the reference section. It describes, 
in alphabetical order, each function of the run-time library pro- 
vided with the Microsoft C Professional Development System. 


Each reference entry gives syntax, return values, and other useful 
information about the library functions. Information on compati- 
bility is supplied to assist you in writing portable programs. 
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About the Run-Time Reference 


The following pages describe, in alphabetical order, the more than 400 func- 
tions in the Microsoft run-time library. In some cases, related routines are 
clustered in the same description. For example, the based, near, and far versions 
of heapwalk are in the same discussion, as are the regular and long double 
versions of the math functions, such as acos and atan. Differences are noted 
where appropriate. Refer to Chapter 2, “Run-Time Routines by Category,” or 
to the index to locate any function that does not appear in the expected position 
within the alphabetical reference. 


The discussion of each function (or group of functions) is divided into the follow- 
ing sections: 


Description. Summarizes the routine’s effect, names the include file(s) contain- 
ing its declaration, illustrates the syntax, and briefly describes the arguments. 


Remarks. Gives a more detailed description of the routine and how it is used. 
Return Value. Describes the value returned by the routine. 


Compatibility. Tells whether the routine is compatible with ANSI C, MS-DOS, 
OS/2, UNIX, and XENIX. 


See Also. Names related routines. 


Example. Gives a complete program showing the use of the routine. 


abort 


16 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


/* ABORT.C: 


Aborts the current process and returns an error code. 


#include <process.h> Required only for function declarations; use either 
#include <stdlib.h> PROCESS.H or STDLIB.H 


void abort( void ); 


The abort function prints the message 


abnormal program termination 


to stderr, then calls raise(SIGABRT). The action taken in response to the SIGABRT signal 
depends on what action has been defined for that signal in a prior call to the signal func- 
tion. The default SIGABRT action is for the calling process to terminate with exit code 3, 
returning control to the parent process or operating system. 


The abort function does not flush stream buffers or do atexit/onexit processing. 


The abort function does not return control to the caller. Rather, it terminates the process 
and, by default, returns an exit code of 3 to the parent process. 


MANS! @ DOS H OS/ WW UNIX MW XENIX 


In multithread libraries, the abort function does not call raise(SIGABRT). Instead, it 
simply terminates the process with exit code 3. 


exec functions, exit, exit, raise, signal, spawn functions 


This tries to open a file and aborts if the attempt fails. */ 


dHinclude <stdio.h> 
#Hinclude <stdlib.h> 


77 | | abort 


void main() 
{ 


FILE *stream; 
if( (stream = fopen( "“NOSUCHF.ILE", "r" )) == NULL ) 
{ 
perror( “Couldn't open file" ); 
abort(); 
} 


else 
fclose( stream ); 


Output 
Couldn't open file: No such file or directory 


abnormal program termination 
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Description Calculates the absolute value. 
#include <stdlib.h> Required only for function declarations; use either STDLIB.H 
#include <math.h> or MATH.H 


int abs( int 77 ); 


n Integer value 
Remarks The abs function returns the absolute value of its integer argument 77. 
Return Value = The abs function returns the absolute value of its argument. There is no error return. 
Compatibility mM ANS! @ DOS m OS/2 Mf UNIX” M@ XENIX. 
See Also cabs, fabs, labs 


Example 


/* ABS.C: This program computes and displays the absolute values of 


* several i ae 


#Finclude <stdio.h> 
dFinclude <math.h> 
fHinclude <stdlib.h> 


void main() 


{ 


int ix = -4, iy; 
long 1x -41567L, ly; 
double dx -~3.141593, dy; 


iy = abst ix ); 
printf( "The absolute value of %d is %d\n", ix, iy); 


ly = labs( 1x ); 
printf( "The absolute value of 41d is %1ld\n", 1x, ly); 


dy = fabs( dx ); 
printf( "The absolute value of 2f is 4f\n", dx, dy ); 


79 abs 


Output 


The absolute value of -4 is 4 
The absolute value of -41567 is 41567 
The absolute value of -3.141593 is 3.141593 


access 
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Description 


Remarks 


Return Value 


Determines file-access permission. 


#include <io.h> Required only for function declarations 


#include <errno.h> Required for definition of errno constants 
int access( char *pathname, int mode ); 


pathname File or directory path name 
mode Permission setting 
With files, the access function determines whether the specified file exists and can be 


accessed in mode. The possible mode values and their meanings in the access call are as 
follows: 


Value Meaning 

00 Check for existence only 

02 Check for write permission 

04 Check for read permission 

06 . Check for read and write permission 


With directories, access determines only whether the specified directory exists; under 
DOS and OS/2, all directories have read and write access. 


The access function returns the value 0 if the file has the given mode. A return value of -1 
indicates that the named file does not exist or is not accessible in the given mode, and 
errno is set to one of the following values: 


Value Meaning 
EACCES Access denied: the file’s permission setting does not allow the 
specified access. 


ENOENT File or path name not found. 


81 aCCess 
a rama 


Compatibility O ANS! #& DOS HW OS/72 WH UNIX’ 8 XENIX 
See Also chmod, fstat, open, stat 
Example 


/* ACCESS.C: This example uses access to check the file named "data" 
* to see if it exists and if writing is allowed. 
*/ 


#tHinclude <io.h> 
#tinclude <stdio.h> 
dHinclude <stdlib.h> 


void main() 
{ 
/* Check for existence */ 
if( (access( “access.c", @ )) != -1 ) 
{ 
printf( "File exists\n" ); 


/* Check for write permission */ 


if( (access( “access.c", 2 )) !=-1 ) 
printf( "File has write permission\n" ); 


Output 


File exists 
File has write permission 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Calculate the arccosine. 


#include <math.h> 


#include <errno.h> Required for definition of errno constant 


double acos( double x ); 


long double acosl( long double x ); 
x Value whose arccosine is to be calculated 


The acos functions return the arccosine of x in the range 0 to m radians. The value of x 
must be between —1 and 1. The acosl function is the 80-bit counterpart, which uses an 80- 
bit, 10-byte coprocessor form of arguments and return values. See the reference page on 
the long double functions for more details on this data type. 


The acos functions return the arccosine result. If x is less than —1 or greater than 1, the 
function sets errno to EDOM, prints a DOMAIN error message to stderr, and returns 0. 
Error handling can be modified with the matherr (or _matherrl) routine. 


acos 


M@ ANS! 9 DOS #8 OS/2 UNIX’ = XENIX 
acosl 


O ANS! @ DOS # OS/f2 OF UNIX OO XENIX 


asin functions, atan functions, cos functions, matherr, sin functions, tan functions 


/* ASINCOS.C: This program prompts for a value in the range -1 to l. 

* Input values outside this range will produce DOMAIN error messages.° 
* If a valid value is entered, the program prints the arcsine and the 
* arccosine of that value. 


*/ 


#Hinclude <math.h> 

dHinclude <stdio.h> 
#Finclude <stdlib.h> 
#Hinclude <errno.h> 
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void main() 
{ 
double x, y; 


printf( “Enter a real number between -1 and 1: " ); 
scanf( "41f", &x ); 

y = asin( x );3 

printf( "“Arcsine of &4f = 4f\n", x, y ); 

y = acos( x ); 

printf( "“Arccosine of %f = %f\n", x, y ); 


Output 


Enter a real number between -1 and 1: .32696 
Arcsine of 9.326968 = 0.333085 
Arccosine of @.32696@ = 1.237711 
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Description Allocates memory on the stack. 
#include <malloc.h> Required only for function declarations 
void *alloca( size_t size ); 
size 4 Bytes to be allocated from stack 


Remarks The alloca routine allocates size bytes from the program’s stack. The allocated space is 
automatically freed when the calling function is exited. 


When you compile with optimization on (either by default or by using one of the /O op- 
tions), the stack pointer may not be restored properly in functions that have no local varia- 
bles and that also reference the alloca function. The following program demonstrates the 
problem: 


/* Compile with CL /Lp /AM /0Ox /Fce */ 
#Hinclude <malloc.h> 


void main( void ) 
func( 10 ); 
a func( register int i ) 
| alloca( i ); 


To ensure that the stack pointer is properly restored, make sure that any function refer- 
encing alloca declares at least one local variable. 


The pointer value returned by alloca should never be passed as an argument to free, nor 
should alloca be used in an expression that is an argument to a function. 


Return Value The alloca routine returns a void pointer to the allocated space, which is guaranteed to be 
suitably aligned for storage of any type of object. To get a pointer to a type other than 
char, use a type cast on the return value. The return value is NULL if the space cannot be 
allocated. 
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See Also calloc functions, malloc functions, realloc functions 


Example 


/* ALLOCA.C: This program checks the stack space available before 
* and after using the alloca function to allocate space on the stack. 
*/ 


#Hinclude <malloc.h> 
#Hinclude <stdio.h> 


void main() 
{ 
char *buffer; 


printf( “Bytes available on stack: %u\n", stackavail() ); 


/* Allocate memory for string. */ 

buffer = alloca( 128 * sizeof( char ) ); 
printf( "Enter a string: “ ); 

gets( buffer ); 

printf( "You entered: %s\n", buffer ); 


printf( “Bytes available on stack: Zu\n", stackavail() ); 


Output 


Bytes available on stack: 2028 

Enter a string: How much stack space will this string take? 
You entered: How much stack space will this string take? 
Bytes available on stack: 19@2 


tt 
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Description 


Remarks 


_ Draw elliptical arcs. 


#include <graph.h> 


short far _are( short x/, short y/, short x2, short y2, short x3, short y3, 
short x4, short y4 ); 


short far _arc_w( double x/, double y/, double x2, double y2, double x3, double y3, 
double x4, double y4 ); 


short far _arc_wxy(struct wxycoord far *pwxy/, struct _wxycoord _far *pwxy2, 
struct _wxycoord far *pwxy3, struct _wxycoord _far *pwxy4 ); 


xl, yl Upper-left corner of bounding rectangle 

WZ ,y2" 3 Lower-right comer of bounding rectangle 

x3, y3 Second point of start vector (center of bounding rectangle is 
first point) | 

x4, y4 Second point of end vector (center of bounding rectangle is 
first point) 

pwxyl Upper-left corner of bounding rectangle 

pwxy2 Lower-right comer of bounding rectangle 

pwxy3 Second point of start vector (center of bounding rectangle is 
first point) 

pwxy4 Second point of end vector (center of bounding rectangle is 
first point) 


The _arc functions draw elliptical arcs. The center of the arc is the center of the bounding 
rectangle, which is defined by points (x/, y/) and (x2, y2) for_are and _are_w and by 
points pwxy/ and pwxy2 for _arc_wxy. The arc starts where it intersects an imaginary line 
extending from the center of the arc through (x3, y3) for __are and _are_w and through 
pwxy3 for _arc_wxy. It is drawn counterclockwise about the center of the arc, ending 
where it intersects an imaginary line extending from the center of the arc through (x4, y4) 
for_are and _are_w and through pwxy4 for _arc_wxy. 


The _arc routine uses the view coordinate system. The _arc_w and _arc_wxy functions 
use the real-valued window coordinate system. 


In each case, the arc is drawn using the current color. Since an arc does not define a closed 
area, it is not filled. 
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Return Value These functions return a nonzero value if the arc is successfully drawn; otherwise, they 
return 0. 

Compatibility O ANS! @ DOS OF oS/7 O UNIX O XENIX 

See Also _ellipse functions, _lineto functions, _pie functions, _rectangle functions, _setcolor 

Example 


/* ARC.C: This program. draws a simple arc. */ 


#tinclude <graph.h> 
d#Finclude <stdlib.h> 
#Hinclude <conio.h> 


void main() 
{ 
short x, y; 
struct xycoord xystart, xyend, xyfill; 


/* Find a valid graphics mode */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


/* Draw arcs */ 

x = 100; y = 100; 

_arc( x - 60, y - 60, x, y, x - 30, y - 60, x - 60, y - 38); 
_arc( x + 60, y + 60, x, y, x, y + 30, x + 30, y ); 


/* Get endpoints of second arc and enclose the figure, then fill it. */ 
_getarcinfo( &xystart, &xyend, &xyfill ); 

_moveto( xystart.xcoord, xystart.ycoord ); 

_lineto( xyend.xcoord, xyend.ycoord ); 

_floodfill( xyfill.xcoord, xyfill.ycoord, _getcolor() ); 


getch(); 
_setvideomode( _DEFAULTMODE ); 
} 
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Description Converts a tm time structure to a character string. 
#include <time.h> 
| char *asctime( const struct tm *timeptr ); 
timeptr Time/date structure 


Remarks The asctime function converts a time stored as a structure to a character string. The 
timeptr value is usually obtained from a call to gmtime or localtime, both of which return 
a pointer to a tm structure, defined in TIME.H. (See gmtime for a complete description of 
the tm structure fields.) 


The tm structure contains the following elements: 


Element Description 

int tm_sec Seconds after the minute (0-59) 
int tm_min Minutes after the hour (0-59) 
int tm_hour Hours since midnight (0-23) 
int tm_mday Day of the month (0-31) 

int tm_mon Months since January (0-11) 
int tm_year Years since 1900 

int tm_wday Days since Sunday (0-6) 

int tm_yday Days since January 1 (0-365) 
int tm_isdst Daylight-saving-time flag 


The string result produced by asctime contains exactly 26 characters and has the form of 
the following example: 


. Wed Jan 82 02:03:55 1980\n\O 


A 24-hour clock is used. All fields have a constant width. The newline character (\n) and 
the null character (’\0’) occupy the last two positions of the string. The asctime function 
uses a single statically allocated buffer to hold the return string. Each call to this routine de- 
stroys the result of the previous call. 


Return Value The asctime function returns a pointer to the character string result. There is no error 
return. 
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Compatibility M ANS! @ DOS HM OS/72 WM UNIX Mf XENIX 


See Also ctime, ftime, gmtime, localtime, time, tzset 


Example 


/* ASCTIME.C: This program places the system time in the long integer aclock, 
* translates it into the structure newtime and then converts it to 

* string form for output, using the asctime function. 

*/ 


#include <time.h> 
dHinclude <stdio.h> 


struct tm *newtime; 
time_t aclock; 


void main() 
time( &aclock ); /* Get time in seconds */ 
newtime = localtime( &aclock ); /* Convert time to struct tm form */ 
/* Print local time as a string */ 
printf( “The current date and time are: %s\n", asctime( newtime ) ); 
Output 


The current date and time are: Thu Jun 15 @6:57:59 1989 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Calculate the arcsine. 


#include <math.h> 


#include <errno.h> 


double asin( double x ); 


long double asinl( long double’ x ); 
x Value whose arcsine is to be calculated 


The asin functions calculate the arcsine of x in the range —1/2 to n/2 radians. The value of 
x must be between —1 and 1. The asinl function is the 80-bit counterpart, which uses an 80- 
bit, 10-byte coprocessor form of arguments and return values. See the reference page on 
the long double functions for more details on this data type. 


The asin functions return the arcsine result. If x is less than —1 or greater than 1, asin sets 
errno to EDOM, prints a DOMAIN error message to stderr, and returns 0. 


Error handling can be modified by using the matherr (or _matherrl) routine. 


asin 
MANS! 9.DOS #8 OS/2 HF UNIX 8 XENIX 
asinl 
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acos functions, atan functions, cos functions, matherr, sin functions, tan functions 


/* ASINCOS.C: This program prompts for a value in the range -1 to l. 
* Input values outside this range will produce DOMAIN error messages. 
* If a valid value is entered, the program prints the arcsine and the 


*] 


* arccosine of that value. 


#Hinclude <math.h> 
#Finclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <errno.h> 
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void main(). 


{ 
double x, y; 


printf( “Enter a real number between -1 and 1: " ); 
scanf( "%1f", &x ); 

y = asin( x ); 

printf( "“Arcsine of 2f = 4f\n", x, y ); 

y = acos( x ); 

printf( “Arccosine of %f = %*f\n", x, y ); 


Output 


Enter a real number between -1 and 1: .32696 
Arcsine of 0.326960 = 0.333085 
Arccosine of 0.326968 = 1.237711 


assert 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


/* ASSERT.C: 


Prints an error message and aborts the program. 


#include <assert.h> 


#include <stdio.h> 

void assert( int expression ); 

expression C expression specifying assertion being tested 

The assert routine prints a diagnostic message and calls the abort routine if expression is 
false (0). The diagnostic message has the form 


Assertion failed: expression, file filename, line linenumber 


where filename is the name of the source file and /inenumber is the line number of the 
assertion that failed in the source file. No action is taken if expression is true (nonzero). 


The assert routine is typically used in program development to identify program logic er- 
rors. The given expression should be chosen so that it holds true only if the program is © 
operating as intended. After a program has been debugged, the special “no debug” identi- 
fier NDEBUG can be used to remove assert calls from the program. If NDEBUG is defined 
(by any value) with a /D command-line option or with a #define directive, the Cc preproces- 
sor removes all assert calls from the program source. 


The assert routine is implemented as a macro. 
None. 


MANS! @ DOS  OS/2 WM UNIX Wf XENIX 


abort, raise, signal 


In this program, the analyze_string function uses the 


* assert function to test several conditions related to string and 


* length. 


If any of the conditions fails, the program prints a 


* message indicating what caused the failure. 


ial 


d#FHinclude <stdio.h> 
#include <assert.h> 
#Finclude <string.h> 
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void analyze_string( char *string ); /* Prototype */ 


void main() 
{ 
char testl[] = "abc", *test2 = NULL, test3({] = ""; 


printf ( “Analyzing string '%s'\n", testl ); 
analyze_string( testl ); 
printf ( “Analyzing string '%s‘\n", test2 ); 
analyze_string( test2 ); , 
printf ( "Analyzing string '%s'\n", test3 ); 
analyze_string( test3 ); 

} 


/* Tests a string to see if it is NULL, empty, or longer than @ characters */ 
void analyze_string( char * string ) 

{ 

assert( string != NULL ); /* Cannot be NULL */ 

assert( *string != '\@' ); /* Cannot be empty */ 

assert( strlen( string ) > 2); /* Length must be greater than 2 */ 

} 7 


Output 
Analyzing string ‘abc' 
Analyzing string '(null)' 


Assertion failed: string != NULL, file assert.c, line 28 


abnormal program termination 


atan Functions | 94 


Description 


Remarks 


Return Value 


Compatibility - 


See Also 


Example | 


Calculate the arctangent of x (atan and atanl) and the arctangent of y/x (atan2 and atan2l). 
#include <math.h> 


double atan( double x ); 

double atan2( double y, double x ); 

long double atanl( long double x ); 

long double atan2I( long double y, long double x ); 


x,y Any number 


The atan family of functions calculates the arctangent of x, and the atan2 family of func- 
tions calculates the arctangent of y/x. The atan group returns a value in the range —77/2 to 
1/2 radians, and the atan2 group returns a value in the range —7 to 1 radians. The atan2 
functions use the signs of both arguments to determine the quadrant of the return value. 


The atan family of functions returns the arctangent result. If both arguments of atan2 or 
atan2I are 0, the function sets errno to EDOM, prints a DOMAIN error message to stderr, 
and returns 0. 


Error handling can be modified by using the matherr (or _matherrl) routine. 


atan, atan2 
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atanl, atan2]1 


O ANS! @ DOS WM oOS2 QO UNIX O XENIX 


acos functions, asin functions, cos functions, matherr, sin functions, tan functions 


/* ATAN.C: This program calculates the arctangent of 1 and as, Sf 


dHinclude <math.h> 
#Finclude <stdio.h> 
#Hinclude <errno.h> 
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void main() 
{ 
double xl, x2, y; 


printf( “Enter a real number: " ); 

scanf( "%1f", &xl ); 

y = atan( xl ); 

printf( "“Arctangent of %f: %f\n", xl, y ); 

printf( "Enter a second real number: " ); 

scanf( "Z41f", &x2 ); 

y = atan2( xl, x2 ); 

printf( “Arctangent of 2f / &f: *f\n", xl, x2, y ); 


Output 


Enter a real number: ~862.42 

Arctangent of -862.420000: -1.569637 

Enter a second real number: 78.5149 

Arctangent of -862.420000 / 78.514900: -1.480006 


atexit 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


. Example 
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Processes the specified function at exit. 

#include <stdlib.h> Required only for function declarations 
int atexit( void ( *func )( void ) ); 

func Function to be called 


The atexit function is passed the address of a function (func) to be called when the pro- 
gram terminates normally. Successive calls to atexit create a register of functions that are 
executed in LIFO (last-in-first-out) order. No more than 32 functions can be registered 
with atexit or onexit. The functions passed to atexit cannot take parameters. 


All routines passed to atexit should have the _loadds attribute if used in multithread 
dynamic-link libraries. 


The atexit function returns 0 if it is successful, or a nonzero value if an error occurs (e.g., 
if there are already 32 exit functions defined). 


MANS! @ DOS #8 OS2 O UNIX O XENI 


Use the ANSI-standard atexit function (rather than the similar onexit function) whenever 


ANSI portability is desired. 


In the OS/2 environment, the atexit function calls the OS/2 function DosExitList. 


abort, exit, exit, onexit 


/* ATEXIT.C: This program pushes four functions onto the stack of functions 
* to be executed when atexit is called. When the program exits, these 
* programs are executed ona "last in, first out" basis. 


tf 


dHinclude <stdlib.h> 
d#Finclude <stdio.h> 
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void fnl( void ), fn2( void ), fn3( void ), fn4( void ); 


void main() 
{ 

atexit( fnl ); 

atexit( fn2 ); 

atexit( fn3 ); 

atexit( fn4 ); 

printf( “This is executed first.\n" ); 
} 


void fnl() 
{ 

printf(. “next.\n" ); 
} 


void fn2() 
{ 

printf( “executed " ); 
} 


void fn3() 
{ 

printf( "is " ); 
} 


void fn4() 
( 

printf( "This " ); 
} 


Output 


This is executed first. 
This is executed next. 
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Description 


Remarks 


Convert strings to double (atof), long double (_atold) integer (atoi), or long (atol). 


#include <math.h> atof, atold 
#include <stdlib.h> atof, atold, atoi, atol 


double atof( const char *string ); 
long double _atold( const char *string ); 


int atoi( const char *string ); 


_long atol( const char *string ); 


string String to be converted 


These functions convert a character string to a double-precision floating-point value (atof), 
an integer value (atoi), a long integer value (atol), or a long double value (_atold). The 
input string is a sequence of characters that can be interpreted as a numerical value of the 
specified type. 


The string size that can be handled by the atof or _atold function is limited to 100 
characters. 


The function stops reading the input string at the first character that it cannot recognize as 
part of a number. This character may be the null character (’\0’) terminating the string. 


The atof and _atold functions expect string to have the following form: 
[whitespace] [{sign}]] [| IKOdigits] [.digits] [{d1D1el E)[sign]digits] \ 


A whitespace consists of space and/or tab characters, which are ignored; sign is either plus 
(+) or minus (—); and digits are one or more decimal digits. If no digits appear before the 
decimal point, at least one must appear after the decimal point. The decimal digits may be 
followed by an exponent, which consists of an introductory letter (d, D, e, or E) and an op- 
tionally signed decimal integer.. 


The atoi and atol functions do not recognize decimal points or exponents. The string argu- 
ment for these functions has the form 


[whitespace] [[sign]]digits 


where whitespace, sign, and digits are exactly as described above for atof. 
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Return Value Each function returns the double, long double, int, or long value produced by interpret- 
ing the input characters as a number. The return value is 0 (for atoi), OL (for atol), and 0.0 
(for atof and _atold) if the input cannot be converted to a value of that type. The return 
value is undefined in case of overflow. 


Compatibility _atof, atoi, atol 
MANS! @ DOS #8 OS/22 HE UNIX BB XENIX 


_atold 
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See Also ecvt, fevt, gcvt 


Example 


/* ATOF.C: This program shows how numbers stored as strings can be 
* converted to numeric values using the atof, atoi, and atol functions. 
*/ 


#Hinclude <stdlib.h> 
dHinclude <stdio.h> 


void main() 
{ 
char *s; double x; int i; long 1; 


Sm" =23909.12E-15"; /* Test of atof */ 
x = atof( s ); 
printf( “atof test: ASCII string: %4s\tfloat: Ze\n", Ss, xX )3 


S = "7.8912654773d210"; /* Test of atof */ 
x = atof( s ); 
printf( “atof test: ASCII string: %s\tfloat: Ze\n", Ss, xX )3 


s =" -9885 pigs"; /* Test of atoi */ 
i= atoi( s ); 
printf( "“atoi test: ASCII string: %s\t\tinteger: %4d\n", s, i ); 


s = "98854 dollars"; /* Test of atol */ 
1 = atol( s ); ; 
printf( “atol test: ASCII string: %s\t\tlong: @ld\n", s, 1 )3 
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Output 


atof test: 
atof test: 
atoi test: 
atol test: 


string: 
string: 
string: 
string: 


-2309.12E-15 
7 .8912654773d210 
-9885 pigs 
98854 dollars 
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float: -2.309128e-912 
float: 7.891265e+2198 
integer: -9885 
long: 98854 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


bdos 


Invokes the DOS system call. 
#include <dos.h> 


int bdos( int dosfunc, unsigned int dosdx, unsigned int dosal ); 


dosfunc Function number 
dosdx DX register value 
dosal AL register value 


_ The bdos function invokes the DOS system call specified by dosfunc after placing the 


values specified by dosdx and dosal in the DX and AL registers, respectively. The bdos 
function executes an INT 21H instruction to invoke the system call. When the system call 
is complete, bdos returns the contents of the AX register. 


The bdos function is intended to be used to invoke DOS system calls that either take no 
arguments or take arguments only in the DX (DH, DL) and/or AL registers. 


Do not use the bdos function to call interrupts that modify the DS register. Instead, use the 
intdosx or int86x function. The intdosx and int86x functions load the DS and ES registers 
from the segregs parameter and also store the DS and ES registers into segregs after the 
function call. 


_ This call should not be used to invoke system calls that indicate errors by setting the carry 


flag. Since C programs do not have access to this flag, your program cannot determine 
whether the return value is an error code. The intdos function should be used in these — 
cases. 


The bdos function returns the value of the AX register after the system call has completed. 
O ANSI @ DOS OF OS/ O UNIX OO XENIX 


intdos, intdosx 


/* BDOS.C: This example calls DOS function @x9 (display string) 
* to display a $-terminated string. 


*/ 


dFinclude <dos.h> 
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/* Function @x@9 assumes that DS will contain segment of the string. 

* This will be true for all memory models if the string is declared near. 
*/ 

char _near str[] = “Hello world!\r\n$"; 


void main() 
{ . 
/* Offset of string must be in DX, segment in DS. AL is not needed, 
* so @ is used. 

*/ 
bdos( @x@9, (int)str, @ ); 


Output 


Hello world! 
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_beginthread 


Description 


Remarks 


Begins thread in OS/2 process. 


#include <process.h> Multithread version of PROCESS.H 


#include <stddef.h> Declaration of threadid variable 


int far _beginthread( void( far *start_address )( void _far * ), 
void _far *stack_bottom, unsigned stack_size, void _far *arglist ); 


start_address Starting address 
stack_bottom Address of the thread stack 
stack_size Stack size for thread 
arglist Argument list for thread 


The _beginthread function creates a thread that begins execution of a far routine at 
start_address. When the thread returns from that far routine, it is terminated automatically. 
The user can also terminate the thread by calling _endthread. 


The address of the thread stack is given by stack_bottom. If stack_bottom is set to NULL, 
the run-time library code will allocate and deallocate the thread stack as needed. Since the 
_beginthread function can determine the current status of all thread IDs, it can free the old 
stack and allocate a new stack whenever a thread is reused. 


If it is not NULL, the stack. bottom argument must specify a word address, and the stack 
must be at least as long as specified by the stack_size argument. Usually this memory is 
either a global array or memory returned by malloc or _fmalloc. 


The stack_size argument must be even and nonzero. 


If you are writing multithread programs that make C run-time calls from child threads, be 
sure to allocate a sufficiently large stack. For example, the C function printf requires 
more than 500 bytes of stack space. To be safe, allocate at least 2,048 bytes for a thread’s 
stack. (If your child thread makes no run-time calls, stack space is generally not a 
problem.) 


As a general rule, you should have 2K of stack space free when calling any API (Applica- 
tions Program Interface) routine (e.g., OS/2 system calls). 


The arglist is a parameter, the size of a far pointer, to be passed to the newly created 
thread. Typically it is the address of a data item, such as a character string, to be passed to 
the new thread. The arglist may be NULL if not needed, but _beginthread should be pro- 
vided with some value to pass to the child thread. 
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All threads will be terminated if any thread calls abort, exit, exit, or DosExit. A good 
practice in multithread programming is to make the first thread the main thread and wait 
until other threads have terminated before exiting the program. 


The OS/2 function DosCreateThread should-not be called directly to create threads. The 
_beginthread function performs initialization procedures required to call other C run-time 
library functions safely. 


Return Value The function returns the thread identification number of the new thread, if successful. A re- 
turn value of —1 indicates an error, and errno is set to one of the following values: 


Value Meaning 
EAGAIN Too many threads 
EINVAL Invalid argument, “bad stack” 
Compatibility CO ANS! OF DOS MOS/72 OO UNIX OD XENIX 
See Also _endthread 
Example 
/* BEGTHRD.C illustrates multiple threads using functions: 
x _beginthread _endthread 
* 
* Also the global variable: 
* _threadid 
*k . ‘ 
* This program requires the multithread library. For example, compile 
* with the following command line: 
2 


CL /MT THREADS.C 
| 


#tdefine INCL_NOCOMMON 

#tdefine INCL_NOPM 

##define INCL_DOSPROCESS 

#tdefine INCL_VIO 

#Hinclude <os2.h> 

#include <process.h> /* _beginthread, _endthread */ 
#Hinclude <stddef.h> /* _threadid 
#Hinclude <stdlib.h> 

#include <conio.h> 


void Bounce( int c ); ~ #® Prototypes :*/ 
void CheckKey( void *dummy ); 
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/* GetRandom returns a random integer between min and max. */ 
#tdefine GetRandom( min, max ) ((rand() % (int)(( (max) + 1) - (min))) + (min)) 


#tdefine STACK_SIZE 4096 


BOOL repeat = TRUE; /* Global repeat flag and video variable */ 
VIOMODEINFO vmi = ( sizeof( VIOMODEINFO ) }; 


void main() 

{ 
PCHAR stack; 
CHAR ch= ''A'; 


/* Get display screen's text row and column information. */ 
VioGetMode( &vmi, @ ); 


/* Launch CheckKey thread to check for terminating keystroke. */ 
_beginthread( CheckKey, NULL, STACK_SIZE, NULL ); 


/* Loop until CheckKey terminates program. */ 

while( repeat ) 

{ 
/* On first loops, launch character threads. */ 
_beginthread( Bounce, NULL, STACK_SIZE, (void *)ch++ ); 


 /* Wait one second between loops. */ 
DosSleep( 10@0L ); 


‘) 


/* CheckKey - Thread to wait for a keystroke, then clear repeat flag. */ 
void CheckKey( void *dummy ) 
{ 
getch(); 
repeat = @; /* _endthread implied */ 
y 


/* Bounce - Thread to create and control a colored letter that moves 
* around on the screen. 

* 

* Params: ch - the letter to be moved 

se 

void Bounce( int ch ) 


{ d 
/* Generate letter and color attribute from thread argument. */ 


char blankcel1(2] = { 9x20, Ox@7 }; 
char blockcell(2] = { ch , (ch % 16) +1); 
int xold, xcur, yold, ycur; 


BOOL FIPSt = TRUE: 


_beginthread 
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/* Seed random number generator and get initial location. */ 
srand( *_threadid ); 
xcur = GetRandom( @, vmi.col - 1 ); 
ycur = GetRandom( @, vmi.row - 1 ); 
while( repeat ) 
{ 
/* Pause between loops. */ 
DosSleep( 186L ); 


/* Blank out our old position on the screen, and draw new letter. 
if( first ) 

first = FALSE; 
else : 
VioWrtCellStr( blankcell, 2, yold, xold, @ ); 
VioWrtCel]Str( blockcell, 2, ycur, xcur, @ ); 


/* Increment the coordinate for next placement of the block. */ 
xold = xcur; 

yold = ycur; 

xcur += GetRandom( -1, 1 ); 

ycur += GetRandom( -1, 1 ); 


/* Correct placement (and beep) if about to go off the screen. */ 
if( xcur < @ ) 
<cur =e 
else if( xcur == vmi.col ) 
xcur = vmi.col - 2; 
else if( ycur < @ ) 
yeur = 1; 
else if( ycur == vmi.row ) 
ycur = vmi.row - 2; 


/* If not at screen border, continue, otherwise beep. */ 
else 
continue; 
DosBeep( (ch - 'A') * 1800, 175 ); 
} 
/* _endthread given (but not really needed) to terminate. */ 
_endthread(); 


sa 
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Bessel Functions 


Description 


Remarks 


Compute the Bessel function. 
#include <math.h> 


double j0( double x ); 

double ji( double x ); 

double jn( int n, double x ); 

double y0( double x ); 

double y1( double x ); 

double yn( int 7, double x ); 

long double _j0l( long double x ); 

long double _jnl( int 1, long double x ); 
long double _jll( long double x ); 

long double _y0I( long double x ); 

long double _y1l( long double x ); 

long double _ynl( int 7, long double x ); 


x . Floating-point value 


n Integer order 


The jO, j1, and jn routines return Bessel functions of the first kind—orders 0, 1, and n, 
respectively. 


The yO, yl, and yn routines return Bessel functions of the second kind—orders 0, 1, and n, 
respectively. The argument x must be positive. 


The long double versions of these functions are the 80-bit counterparts and use the 80-bit, 
10-byte coprocessor form of arguments and return values. See the reference page on the 
long double functions for more details on this data type. 


The Bessel functions are explained more fully in most mathematics reference books, such 
as the Handbook of Mathematical Functions (Abramowitz and Stegun; Washington: U.S. 

Government Printing Office, 1964). These functions are commonly used in the mathemat- 
ics of electromagnetic wave theory. 
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Return Value These functions return the result of a Bessel function of x. 


For y0, yl, or yn, if x is negative, the routine sets errno to EDOM, prints a DOMAIN error 
message to stderr, and returns -HUGE_VAL. 


Error handling can be modified by using the matherr (or _matherrl) routine. 
Compatibility 50, jl, jn, yO, y1, yn. 
O ANS! m@ DOS m OS MM UNIX i XENIX 


_j0l, jul, _jnl, _yOl, _yll, _ynl 


O ANS! @ DOS # OS O UNIX O XENIX 


See Also matherr 

Example 

/* BESSEL.C: This program illustrates Bessel functions, including: 

* ja jl jn yO yl yn 
x) 


fHinclude <math.h> 
fHinclude <stdio.h> 


void main() 

{ 
double x = 2.387; 
int n= 3, ¢c; 


printf( “Bessel functions for x = @f:\n", x ); 
printf( " Kind\t\tOrder\t\Function\tResult\n\n" ); 
printf( " First\t\t@\tjO( x )\t\taf\n", jO( x ) ); 
printf( “ First\t\tl\tjl( x )\t\t2f\n", jl( x ) ); 
Tore © @ 286 <5 cre} 
printf( " First\t\t%d\tjn( n, x )\taf\n", c, jn(c, x ) ); 


printf( " Second\t@\tyO( x )\t\t%f\n", yOC x ) ); 
printf( " Second\tl\tyl( x )\t\tzZf\n", yl( x ) ); 
Ort CS 2s 6 < 5s Cer | 
printf( " Second\t%d\tyn( n, x )\t%f\n", c, yn( c, x ) ); 
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Output 

Bessel functions for x = 2.387000: 
Kind Order Function Result 
First Q j@( x ) 0.009288 
First 1 jl( x ) 0.522941 
First 2 jn( n, x ) @.428870 
First 3 jn( n, x ) 8.195734 
First 4 jn( on, x ) 8.863131 
Second Q yO( x ) @.511681 
Second 1 yl( x ) 8.994374 
Second 2 yn( n, x ) -@.432608 
Second 3 yn( n, x ) -@.819314 
Second 4 yn( n, x ) -1.626833 
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SS A LP, Se EL I a EE Se LE IST ee) 
Description Frees a specified based heap. 
#include <malloc.h> Required only for function declarations 
int bfreeseg( segment seg ); 
seg Segment selected 
Remarks The _bfreeseg function frees a based heap. The seg argument is a based heap returned by 
an earlier call to_bheapseg. It specifies the based heap to be freed. 
The number of bytes freed is the number of bytes specified when the block was allocated. 


After the call, the freed heap is again available for allocation. 


Return Value The _bfreeseg function returns 0 if successful and —1 in the case of an error. 


Compatibility O ANS| @& DOS # OS/72 UO UNIX O XENIX 
See Also _bheapseg, calloc functions, free functions, malloc functions, realloc functions 
Example 


/* BHEAPSEG.C: This program C illustrates dynamic allocation of based 
* memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree. 
“* / 


dHinclude <stdio.h> 

#Hinclude <malloc.h> 
fHinclude <stdlib.h> 
fHinclude <string.h> 


void main() 

{ 
_segment seg; 
char _based( seg ) *outstr, _based( seg ) *instr; 
char _based( seg ) *pout, _based( seg ) *pin; 
char tmpstr(80]; 
int len; 


printf( "Enter a string: " ); 
gets( tmpstr ); 


/* Request a based heap. Use based so that memory won't be taken from 
* near heap. 
iad | 
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if( (seg = _bheapseg( 1000 )) == _NULLSEG ) 
exit( 1 ); 


/* Allocate based memory for two strings. */ 

len = strien( tmpstr ); 

if( (Cinstr = _bmalloc( seg, len +1 )) 
(C(outstr = _bmalloc( seg, len +1 )) 
exit( 1 ); 


_NULLOFF) || 
= _NULLOFF) ) 


/* Copy a lowercased string to dynamic memory. The based memory is 
* far when addressed as a whole. 

*/ 
_fstriwr( _fstrcpy( (char _far *)instr, (char _far *)tmpstr ) ); 
/* Copy input string to output string in reversed order. When reading 

* and writing individual characters from a based heap, the compiler wil] 
* try to process them as near, thus speeding up the processing. 

ar 
for( pin = instr + len - 1, pout = outstr; 

pout < outstr + len; pin--, pout++ ) 
“pout = * pan; 

*pout = ‘\0'; 


/* Display strings. Again strings as a whole are far. */ 
printf( “Input: @Fs\n", (char _far *)instr ); 
printf( "Output: @Fs\n", (char _far *)outstr ); 


/* Free blocks and release based agen: a | 
_bfree( seg, instr ); 

_bfree( seg, outstr ); 

_bfreeseg( seg ); 


Output 


Enter a string: Was I god 
Input: was i god 
Output: dog i saw 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example __. 


Allocates a based heap. 

#include <malloc.h> Required only for function declarations 
_segment _bheapseg( size_t size ); 

size Segment size to allocate 


The _bheapseg function allocates a based-heap segment of at least size bytes. (The block 
may be larger than size bytes because of space required for alignment and for maintenance 
information.) 


The heap code will try to enlarge the heap as necessary. If the original block of memory is 
depleted (e.g., by calls to_bmalloc and _brealloc), the run-time code will try to enlarge 
the heap as necessary. 


The value returned by _bheapseg is the identifier of the based-heap segment. This value 
should be saved and used in subsequent calls to other based-heap functions. 


The _bheapseg function can be called repeatedly. For each call, the C library will allocate 
anew based-heap segment. 


The _bheapseg function returns the newly allocated segment selector that the user must 
save for use in subsequent based-heap functions. A return value of —1 indicates failure. 


Always check the return from the _bheapseg function (especially when it is used in real 
mode), even if the amount of memory requested is small. 


O ANS! @ DOS mM OS QO UNIX OF XENIX 


calloc functions, free functions, malloc functions, realloc functions 


/* BHEAPSEG.C: This program C illustrates dynamic allocation of based 
* memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree. 


a 


#Hinclude <stdio.h> 
#Finclude <malloc.h> 
dFinclude <stdlib.h> 
dHinclude <string.h> 
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void main() 

{ 
_segment seg; 
char _based( seg ) *outstr, _based( seg ) *instr; 
char _based( seg ) *pout, _based( seg ) *pin; 
char tmpstr([80]; 
int len; 


printf( "Enter a string: " ); 
gets( tmpstr ); 


/* Request a based heap. Use based so that memory won't be taken from 
* near heap. 
*/ 
if( (seg = _bheapseg( 1000 )) == _NULLSEG ) 
exit( 1 ); 


/* Allocate based memory for two strings. */ 
len = strien( tmpstr ); 


if( (Cinstr = _bmalloc( seg, Jen + 1 )) == _NULLOFF) || 
((outstr = _bmalloc( seg, len + 1 )) == _NULLOFF) ) 
exit( 1 ); 


/* Copy a lowercased string to dynamic memory. The based memory is 
* far when addressed as a whole. 
*/ 

_fstriwr( _fstrcpy( (char _far *)instr, (char _far *)tmpstr ) ); 


/* Copy input string to output string in reversed order. When reading 

* and writing individual characters from a based heap, the compiler will 
* try to process them as near, thus speeding up the processing. 

mY 

for( pin = instr + len - 1, pout = outstr; 

pout < outstr + len; pin--, pout++ ) 
*pout = *pin; 
*pout = ‘\O'; 


/* Display strings. Again, strings as a whole are far. */ 
printf( “Input: %Fs\n", (char _far *)instr ); 
printf( “Output: 2Fs\n", (char _far *)outstr ); 


/* Free blocks and release based heap. */ 
_bfree( seg, instr ); 

_bfree( seg, outstr ); . 
_bfreeseg( seg ); 
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Output 
Enter a string: Was I god 


Input: was i god 
Output: dog i saw 
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_bios_disk 


Description 


Remarks 


Calls BIOS disk services using system call INT 0x13. 
#include <bios.h> 
unsigned _bios_disk( unsigned service, struct diskinfo_t *diskinfo ); 


service - Disk function desired 


diskinfo Disk parameters 


The _bios_disk routine uses system call INT 0x13 to provide several disk-access func- 
tions. The service parameter selects the function desired, while the diskinfo structure pro- 
vides the necessary parameters. Note that the low-level disk operations allowed by the 
_bios_disk routine are very dangerous to use because they allow direct manipulation of 
the disk. 


The diskinfo structure provides the following parameters: 


Element Description 

unsigned drive Drive number 

unsigned head Head number 

unsigned track Track number 

unsigned sector Starting sector number 

unsigned nsectors Number of sectors to read, write, or compare 

void far *buffer Memory location to write to, read from, or compare 


The service argument can be set to one-of the following manifest constants: 


Constant . Function 


_DISK_FORMAT Formats the track specified by diskinfo. The head and track 
fields indicate the track to format. Only one track can be for- 
matted in a single call. The buffer field points to a set of sector 
markers. The format of the markers depends on the type of 
disk drive; see a technical reference to the PC BIOS to deter- 
mine the marker format. There is no return value. 
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_DISK_READ 


_DISK_RESET 


_DISK_STATUS 


Reads one or more disk sectors into memory. This service 
uses all fields of the structure pointed to by diskinfo, as de- 
fined earlier in this section. If no error occurs, the function re- 
turns 0 in the high-order byte and the number of sectors read 
in the low-order byte. If there is an error, the high-order byte 
will contain a set of status flags. If there is an error, the high- 
order byte will contain a set of status flags, as defined under 
_DISK_READ. Status is returned in the 8 high-order bits of 
the return value, as listed below: 


Bits Meaning 

0Ox01** Invalid request or a bad command 
0x02** Address mark not found 

0x04** Sector not found 

Ox05** Reset failed 

Ox07** Drive parameter activity failed 
0x09** Direct Memory Access (DMA) overrun 
OxOA** Bad sector flag detected 

Ox 10** Data read (ECC) error 

Ox 11** Corrected data read (ECC) error 
0x20** Controller failure 

0x40** Seek error 

Ox80** Disk timed out or failed to respond 
OxAA** — Drive not ready 

OxBB** Undefined error 

OxCC** Write fault on drive 


OxEO** Status error 


Forces the disk controller to do a hard reset, preparing for 
floppy-disk I/O. This is useful after an error occurs in another 
operation, such as a read. If this service is specified, the 
diskinfo argument is ignored. 


Obtains the status of the last disk operation. If this service is 
specified, the diskinfo argument is ignored. 
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_DISK_VERIFY Checks the disk to be sure the specified sectors exist and can 
be read. It also runs a CRC (cyclic redundancy check) test. 
This service uses all fields (except buffer) of the structure 
pointed to by diskinfo, as defined earlier in this section. If no 
error occurs, the function returns 0 in the high-order byte and 
the number of sectors compared in the low-order byte. If there 
is an error, the high-order byte will contain a set of status 
flags, as defined under _DISK_READ (above). 


_DISK_WRITE Writes data from memory to one or more disk sectors. This 
service uses all fields of the structure pointed to by diskinfo, 
as defined earlier in this section. If no error occurs, the func- 
tion returns 0 in the high-order byte and the number of sectors 
written in the low-order byte. If there is an error, the high- 
order byte will contain a set of status flags, as defined under 
_DISK_READ (above). 


Return Value The _bios_disk function returns the value in the AX register after the BIOS interrupt. 
Compatibility O ANS! @ DOS OF OS/72 QO UNIX O XENIX 
Example 


/* BDISK.C: This program first attempts to verify a disk by using an 

* invalid disk head number. After printing the return value error code, 
* the program verifies the disk by using a valid disk head code. 

ia 


dHinclude <conio.h> 
dHinclude <stdio.h> 
#Hinclude <bios.h> 


void main() 
{ 
unsigned status = @; 
struct diskinfo_t disk_info; 


disk_info.drive = Q; 

disk_info.head = 10; /* Invalid head number */ 

disk_info.track = ] 

disk_info.sector = 2 
= 8 


disk_info.nsectors 
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printf( "Insert disk in drive A: and press any key\n" ); 
getch(); 
status = _bios_disk( _DISK_VERIFY, &disk_info ); 
printf( "Return value: @x%.4x\n", status ); 
if( status & Oxff@O ) /* Error if high byte is @ */ 
printf( "Seek error\n" ); 
else 
printf( "No seek error\n" ); 


printf( "Press any key\n" ); 

getch(); 

disk_info.head = @; /* Valid head number */ 

status = _bios_disk( _DISK_VERIFY, &disk_info ); 

printf( "Return value: @x%.4x\n", status ); 

if( status & Oxff@O ) /* Error if high byte is @ */ 
printf( "Seek error\n" ); 

else 
printf( "No seek error\n" ); 


Output 


Insert disk in drive A: and press any key 
Return value: Ox8400 

Seek error 

Press any key 

Return value: @x@@@8 

No seek error 
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Description ~ Calls BIOS equipment-list service, using system call INT 0x11. 
#include <bios.h> 
unsigned _bios_equiplist( void ); 


Remarks The _bios_equiplist routine uses system call INT 0x11 to determine what hardware and 
peripherals are currently installed on the machine. 


Return Value The function returns a set of bits indicating what is installed, as defined below: 
Bits Meaning 
0 Any disk drive installed if true 
1 True (1) if math coprocessor installed 
2-3 System RAM in 16K blocks (16-64K) 
4-5 Initial video mode 
6-7 Number of floppy-disk drives installed (00 =1, 01 = 2, etc.) 
8 False (0) if and only if a Direct Memory Access (DMA) chip 
is installed 
9-11 Number of RS232 serial ports installed 
12 True (1) if and only if a game adapter is installed 
13 True (1) if and only if an internal modem is installed 
14-15 Number of printers installed 


Compatibility O ANS! @ DOS OF 0S/7?2 0 UNIX O XENIX 


Example 


/* BEQUIPLI.C: This program checks for the presence of diskettes. */ 


#Hinclude <bios.h> 
#Hinclude <stdio.h> 
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void main() 
{ 
unsigned equipment; 


equipment = _bios_equiplist(); 

printf( "Equipment bits: @x%.4x\n", equipment ); 

if( equipment & 0x1900 ) /* Check for game adapter bit */ 
printf( "Game adapter installed\n" ); 

else 
printf( "No game adapter installed\n" ); 


Output 


Equipment bits: 9x4061 
No game adapter installed 
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$m PSS PSS SP 
Description Calls BIOS keyboard services, using INT 0x16. 

#include <bios.h> 

unsigned _bios_keybrd( unsigned service ); 

service Keyboard function desired 


Remarks The _bios_keybrd routine uses system call INT 0x16 to access the keyboard services. The 
service argument can be any of the following manifest constants: 


Constant Meaning 
_KEYBRD_READ, Reads the next character from the key- 
_NKEYBRD_READ board. If no character has been typed, the 


call will wait for one. If the low-order 
byte of the return value is nonzero, the 
call contains the ASCII value of the char- 
acter typed. The high-order byte contains 
the keyboard scan code for the character. 
The NKEYBRD_READ constant is used 
with enhanced keyboards to obtain the 
scan codes for function keys Fl1 and F12 
and the cursor control keys. 


_KEYBRD_READY, Checks whether a keystroke is waiting to 

_NKEYBRD_READY be read and, if so, reads it. The return 
value is 0 if no keystroke is waiting, or it 
is the character waiting to be read, in the 
same format as the KEYBRD_READ or 
_NKEYBRD_READY return. This service 
does not remove the waiting character 
from the input buffer, as does the 
_KEYBRD_READ or NKEYBRD_READ 
service. The NKEYBRD_READY con- 
stant is used with enhanced keyboards to 
obtain the scan codes for function keys Fl1 
and F12 and the cursor control keys. 
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Return Value 


_KEYBRD_SHIFTSTATUS, 
_NKEYBRD_SHIFTSTATUS 


Bit 


00H 


01H 
02H 
3H 

04H 
05H 
06H 
07H 
08H 
09H 
OAH 
OBH 
0CH 
0ODH 
0EH 
OFH 


Returns the current SHIFT-key status. Only 
the low-order byte of the return value is af- 
fected. The NKEYBRD_SHIFTSTATUS 
constant is used to get a full 16-bit status 
value. Any combination of the following 
bits may be set: 


Meaning if True 
Rightmost SHIFT key pressed 
Leftmost SHIFT key pressed 
Either CTRL key pressed 
Either ALT key pressed 
SCROLL LOCK on 

NUM LOCK on 

CAPS LOCK on 

In insert mode (INS) 

Left CTRL key pressed 

Left ALT key pressed 

Right CTRL key pressed 
Right ALT key pressed 
SCROLL LOCK key pressed 
NUM LOCK key pressed 
CAPS LOCK key pressed 


SYS REQ key pressed 


With the ...READ and ...SHIFTSTATUS arguments, the _bios_keybrd function returns the 


contents of the AX register after the BIOS call. 


With the ..READY argument, bios_keybrd returns 0 if there is no key. If there is a key, 
_bios_keybrd returns the key waiting to be read (i.e. the same value as KEYBRD_READ). 


With the ...READ and the .. READY arguments, the _bios_keybrd function returns —1 if 
CTRL+BREAK has been pressed and is the next keystroke to be read. 
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/* BKEYBRD.C: This program prints a message on the screen until the 
* right SHIFT key is pressed. 
it 


#Hinclude <bios.h> 
dfinclude <stdio.h> 


void main() 
{ 
while( !(_bios_keybrd( _KEYBRD_SHIFTSTATUS ) & @8@@1) ) 
printf( “Use the right SHIFT key to stop this message\n" ); 
printf( "Right SHIFT key pressed\n" ); 
} 


Output 


Use the right SHIFT key to stop this message 
Use the right SHIFT key to stop this message 
Use the right SHIFT key to stop this message 
Use the right SHIFT key to stop this message 
Right SHIFT key pressed 
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Description 


Remarks 


Return Value 


Compatibility 


Example 


Calls the BIOS memory-size service, using system call INT 0x12. 
#include <bios.h> 
unsigned _bios_memsize( void ); 


The _bios_memsize routine uses system call INT 0x12 to determine the total amount of 
main memory installed. 


The routine returns the total amount of installed memory in 1K blocks. The maximum re- 
turn value is 640, representing 640K of main memory. 
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/* BMEMSIZE.C: This program displays the amount of memory installed. */ 


fHinclude <bios.h> 
#Hinclude <stdio.h> 


void main() 


{ 


unsigned memory; 


memory = _bios_memsize(); 
printf ( "The amount of memory installed is: %dK\n", memory ); 


Output 


The amount of memory installed is: 639K 
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_bios_printer 


Description 


Remarks 


Calls BIOS printer services using system call INT 0x17. 
#include <bios.h> 


unsigned _bios_printer( unsigned service, unsigned printer, unsigned data ); 


service Printer function desired 
printer Target printer port 
data Output data 


The _bios_printer routine uses system call INT 0x17 to perform printer output services 
for parallel printers. The printer argument specifies the affected printer, where 0 is LPT1, 
1 is LPT2, and so forth. 


Some printers do not support the full set of signals. As a result, the “Out of Paper” condi- 
tion, for example, may not be returned to your program. 


The service argument can be any of the following manifest constants: 


Constant Meaning 

_PRINTER_INIT Initializes the selected printer. The data argument is ignored. 
The return value is the low-order status byte defined below. 

_PRINTER_STATUS Returns the printer status in the low-order status byte defined 


below. The data argument is ignored. 


_PRINTER_WRITE Sends the low-order byte of data to the printer specified by 
printer. The low-order byte of the return value indicates the 
printer status after the operation, as defined below: 


Bit Meaning if True 


0 Printer timed out 
1 Not used 

Z Not used 

3 1/O error 

4 Printer selected 
5 Out of paper 

6 Acknowledge 

7 Printer not busy 
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Return Value The _bios_printer function returns the value in the AX register after the BIOS interrupt. 
Compatibility O ANS! M@ DOS OF O0S72 UO UNIX O XENIX 
Example 


/* BPRINTER.C: This program checks the status of the printer attached to 
* LPT1 when it is off line, then initializes the printer. 
*/ 


dHinclude <bios.h> 
##include <conio.h> 
d#Hinclude <stdio.h> 


dtdefine LPT1 @ 


void main() 
{ 


unsigned status; 


printf ( "Place printer off line and press any key\n" ); 
getch(); 


Status = _bios_printer( _PRINTER_STATUS, LPT1l, @ ); 

printf( “Status with printer off line: @x%.4x\n\n", status ); 
printf( “Put the printer on line and then\n" ); 

printf( “Press any key to initialize printer\n" ); 

getch(); 


status = _bios_printer( _PRINTER_INIT, LPT1, @ ); 
printf( "Status after printer initialized: @x%.4x\n", status ); 


Output 


Place printer off line and press any key 
Status with printer off line: @x9@18 


Put the printer on line and then 
Press any key to initialize printer 
Status after printer initialized: @x9@9@ 
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Description Calls BIOS communications services, using system call INT 0x14. 
#include <bios.h> 
unsigned _bios_serialcom( unsigned service, unsigned serial_port, unsigned data ); 
service Communications service 
serial_port Serial port to use 
data Port configuration bits 
Remarks The _bios_serialcom routine uses system call INT 0x14 to provide serial communications 


services. The serial_port argument is set to 0 for COM1, to 1 for COM2, and so on. 


The _bios_serialcom routine may not be able to establish reliable communications at baud 
rates in excess of 1,200 baud (_COM_1200) due to the overhead associated with servicing 
computer interrupts. Faster data communication rates are possible with more direct pro- 
gramming of serial-port controllers. See C Programmer’ s Guide to Serial Communications 
for more details on serial-communications programming in C. 


The service argument can be set to one of the following manifest constants: 


Constant Service 

_COM_INIT Sets the port to the parameters specified in the data argument 
_COM_SEND | Transmits the data characters over the selected serial port 
_COM_RECEIVE Accepts an input character from the selected serial port 
_COM_STATUS Returns the current status of the selected serial port 


The data argument is ignored if service is set to_COM_RECEIVE or _COM_STATUS. 
The data argument for COM_INIT is created by combining (with the OR operator) one or 
more of the following constants: 


Constant Meaning 
_COM_CHR7 7 data bits 
_COM_CHR8 | 8 data bits 
_COM_STOPI 1 stop bit 
_COM_STOP2 2 stop bits 


_COM_NOPARITY No parity 
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Return Value 


_COM_EVENPARITY 
_COM_ODDPARITY 
_COM_110 
_COM_150 
_COM_300 
_COM_600 
_COM_1200 
_COM_2400 
_COM_4800 
_COM_9600 


Even parity 
Odd parity 
110 baud 
150 baud 
300 baud 
600 baud 
1,200 baud 
2,400 baud 
4,800 baud 
9,600 baud 


The default value of data is 1 stop bit, no parity, and 110 baud. 


The function returns a 16-bit integer whose high-order byte contains status bits. The mean- 
ing of the low-order byte varies, depending on the service value. The high-order bits have 


the following meanings: 


Bit 
15 
14 
13 
12 


Meaning if Set 

Timed out 

Transmission-shift register empty 
Transmission-hold register empty 
Break detected 

Framing error 

Parity error 

Overrun error 


Data ready 


When service is_COM_SEND, bit 15 will be set if data could not be sent. 


When service is_COM_RECEIVE, the byte read will be returned in the low-order bits if 
the call is successful. If an error occurs, any of the bits 9, 10, 11, or 15 will be set. 
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When service is COM_INIT or _COM_STATUS, the low-order bits are defined as 
follows: 


Bit Meaning if Set 
Receive-line signal detected 
Ring indicator 


Data set ready 


Change in receive-line signal detected 
Trailing-edge ring indicator 


7 
6 
5 
4 Clear to send 
3 
2 
1 Change in data-set-ready status 
0 


Change in clear-to-send status 


Note that this function works only with IBM personal computers and true compatibles. 


Compatibility O ANS! M@ DOS OF 0S/f O UNIX O XENIX 


Example 
/* BSERIALC.C: This program checks the status of serial port COM1. */ 


iHinclude <bios.h> 
#Hinclude <stdio.h> 


void main() 

{ 
unsigned coml_status; 
coml_status = _bios_serialcom( _COM_STATUS, @, @ ); 
printf ( “COM1 status: @x%.4x\n", coml_status ); 

} 

Output 


COM1 status: 9x6080 
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Description Calls BIOS time and date services, using system call INT Ox1A. 
#include <bios.h> 


unsigned _bios_timeofday( unsigned service, long *timeval ); 


service Time function desired 
timeval Clock count - 
Remarks The _bios_timeofday routine uses system call INT Ox1A to get or set the clock count. The 


service argument can be either of the following manifest constants: 


Constant Meaning 


_TIME_GETCLOCK Copies the current value of the clock count to the location 
pointed to by timeval. If midnight has not passed since the last 
time the system clock was read or set, the function returns 0; 
otherwise, the function returns 1. 


_TIME_SETCLOCK Sets the current value of the system clock to the value in the 
location pointed to by timeval. There is no return value. 


Return Value The _bios_timeofday function returns the value in the AX register after the BIOS 
interrupt. 


Compatibility QO) ANS! @ DOS O OS UO UNIX OC XENIX 


Example 


/* BTIMEOFD.C: This program gets the current system clock count before and after 
* a "do-nothing" loop and displays the difference. 
* / ; 


#Hinclude <bios.h> 
dHinclude <stdio.h> 
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void main() 
{ 
long i, begin_tick, end_tick; 


_bios_timeofday( _TIME_GETCLOCK, &begin_tick ); 
printf( “Beginning tick count: %lu\n", begin_tick ); 
for( i = 1; i <= 900000; i++ ) 


_bios_timeofday( _TIME_GETCLOCK, &end_tick ); 
printf( “Ending tick count: %lu\n", end_tick ); 
printf( “Elapsed ticks: alu\n", end_tick - begin_tick ); 


Output 


Beginning tick count: 1114255 
Ending tick count: 1114287 
Elapsed ticks: 32 
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Description — Performs binary search of a sorted array. 
#include <stdlib.h> Required for ANSI compatibility 
#include <search.h> Required only for function declarations 


void *bsearch( const void *key, const void *base, size_t num, size_t width, 
int ( *compare )( const void *elem/, const void *elem2 ) ); 


key Object to search for 

base Pointer to base of search data 

num Number of elements 

width Width of elements 

compare Function that compares two elements: elem! and elem2 

eleml | Pointer to the key for the search 

elem2 Pointer to the array element to be compared with the key 
Remarks | The bsearch function performs a binary search of a sorted array of num elements, each of 


width bytes in size. The base value is a pointer to the base of the array to be searched, and 
key is the value being sought. 


The compare argument is a pointer to a user-supplied routine that compares two array ele- 
ments and returns a value specifying their relationship. The bsearch function calls the 
compare routine one or more times during the search, passing pointers to two array ele- 
ments on each call. The routine compares the elements, then returns one of the following 


values: 

Value Meaning 

<0 elem1 less than elem2 
=0 elem! identical to elem2 
>0 elem! greater than elem2 


If the array you are searching is not in ascending sort order, bsearch does not work prop- 
erly. If the array contains duplicate records with identical keys, there is no way to predict 
which of the duplicate records will be located by bsearch. 


Return Value The bsearch function returns a pointer to the first occurrence of key in the array pointed to 
by base. If key is not found, the function returns NULL. 
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Compatibility @ ANS! @ DOS Sf 0s/2 @ UNIX HF XENIX 
See Also Ifind, search, qsort 
Example 


/* BSEARCH.C: This program reads the command-line arguments, sorting them 
* with qsort, and then uses bsearch to find the word “cat." 
*/ 


dHinclude <search.h> 
dHinclude <string.h> 
dHinclude <stdio.h> - 


int compare( char **argl, char **arg2 ); /* Declare a function for compare */ 


void main( int argc, char **argv ) 


{ 


char **result; 
char *key = "cat"; 
int i; 


/* Sort using Quicksort algorithm: */ 
qsort( (char *)argv, argc, sizeof( char * ), compare ); 


for( i = @; i < argc; ++i ) /* Output sorted list */ 
printf( "%s ", argvLi] ); 


/* Find the word "cat" using a binary search algorithm: */ 
result = (char **)bsearch( (char *) &key, (char *)argv, argc, 
sizeof( char * ), compare ); 
if( result ) F 
printf( “\n%s found at 4Fp\n", *result, result ); 
else 
printf( “\nCat not found!\n" ); 
} 


int compare( char **argl, char **arg2 ) 
/* Compare all of both strings: */ 
return strcempi( *argl, *arg2 ); 


Output 


CC:\LIBREF] bsearch dog pig horse cat human rat cow goat 
bsearch cat cow dog goat horse human pig rat 
cat found at 9292:@FD@ 
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Description Calculate absolute value of a complex number. 
#include <math.h> 


double cabs( struct complex z ); 


long double cabsI( struct _complexl z ); 
Z Complex number 


Remarks The cabs and cabsl functions calculate the absolute value of a complex number, which 
must be a structure of type complex (or _complexl). The structure z is composed of a real 
component x and an imaginary component y. A call to one of the cabs routines is equiv- 
alent to the following: . 


sqrt( z.x*z.x + z.y*z.y ) 
The cabsl function is the 80-bit counterpart and it uses the 80-bit, 10-byte coprocessor 


form of arguments and return values. See the reference page on the long double functions 
for more details on this data type. 


Return Value On overflow, these functions call matherr or _matherrl, return HUGE_VAL, and set 
errno to ERANGE. 


Compatibility cabs 


O ANS! @ DOS @ OS/72 MW UNIX Wf XENIX 


cabsl 


O ANS! @ DOS WM OS/2 O UNIX OO XENIX 


See Also abs, fabs, labs 


Example 


/* CABS.C: Using cabs, this program calculates the absolute value of 
* a complex number. 
a J 


dFinclude <math.h> 
dHinclude <stdio.h> 
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void main() 

{ 
struct complex number = { 3.0, 4.9 ); 
double d; 


d = cabs( number ); 


printf( "The absolute value of %@f + 2fi is 4f\n", 
number.x, number.y, d ); 


Output 


The absolute value of 3.@00800 + 4.900000i1 is 5.009000 
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Description 


Remarks 


Return Value’ 


Allocate an array in memory with elements initialized to 0. 


#include <stdlib.h> For ANSI compatibility (calloc only) 


#include <malloc.h> Required only for function declarations 


void *calloc( size_t num, size_t size ); 
void _based( void ) *_bcalloc( segment seg, size_t num, size_t size ); 
void far * fcalloc( size_t num, size_t size ); 


void _near *_ncalloc( size_t num, size_t size ); 


num Number of elements 
size Length in bytes of each element 
seg Segment selector 


/ 
The calloc family of functions allocates storage space for an array of num elements, each 
of length size bytes. Each element is initialized to 0. 


In large data models (compact-, large-, and huge-model programs), calloc maps to 
_fcalloc. In small data models (tiny-, small-, and medium-model programs), calloc maps 
to_ncalloc. 


The various calloc functions allocate storage space in the data segments shown in the list 
below: 


Function Data Segment 

calloc Depends on data model of program 

_bcalloc Based heap, specified by seg segment selector 
_fcalloc Far heap (outside default data segment) 
_ncalloc Near heap (inside default data segment) 


The calloc functions return a pointer to the allocated space. The storage space pointed to 
by the return value is guaranteed to be suitably aligned for storage of any type of object. 
To get a pointer to a type other than void, use a type cast on the return value. 


The _fcalloc and _ncalloc functions return NULL if there is insufficient memory available 
or if num or size is 0. The _bcalloc function returns _NULLOFF in this case. 
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Compatibility calloc 
@ ANS! @ DOS HH OS/2 MW UNIX’ =@ XENIX 


_bcalloc, fcalloc, _ncalloc 


O ANS! @ DOS # OS/2 OF UNIX OO XENIX 


See Also free functions, halloc, hfree, malloc functions, realloc functions 


Example 


/* CALLOC.C: This program uses calloc to allocate space for 40 long integers. 
* It initializes each element to zero. 
*} 


dHinclude <stdio.h> 
dHinclude <malloc.h> 


void main() 
{ 
long *buffer; 


buffer = (long *)calloc( 48, sizeof( long ) ); 
if( buffer != NULL ) 

printf( "Allocated 48 long integers\n" ); 
else 

printf( “Can't allocate memory\n" ); 
free( buffer ); 


Output 


Allocated 4@ long integers 
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Description Calculate the ceiling of a value. 
#include <math.h> 


double ceil( double x ); 
long double ceill( long double x ); 


x Floating-point value 


Remarks The ceil and ceill functions return a double (or long double) value representing the 
smallest integer that is greater than or equal to x. 


The ceill function is the 80-bit counterpart and it uses the 80-bit, 10-byte coprocessor form 
of arguments and return values. See the reference page on the long double functions for 
more details on this data type. 


Return Value These functions return the double or long double result. There is no error return. 


Compatibility ceil 


MANS! @ DOS #8 OS/2 WF UNIX’ 8 XENIX 
ceill 


O ANS! @ DOS MH OS/72 OF UNIX OC XENIX 


See Also floor, fmod 


Example 


/* FLOOR.C: This example displays the largest integers less than or equal 
* to the floating-point values 2.8 and -2.8. It then shows the smallest 
* jntegers greater than or equal to 2.8 and -2.8. 

*/ ; 


dHinclude <math.h> 
#include <stdio.h> 
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void main() 
{ 
double y; 


y = floor( 2.8 ); 

printf( "The floor of 2.8 is @f\n", y ); 
y = floor( -2.8 ); 

printf( “The floor of -2.8 is 4f\n", y ); 


y = ceil( 2.8 ); 

printf( “The ceil of 2.8 is %f\n", y ); 
y = ceil( -2.8 ); 

printf( “The ceil of -2.8 is %f\n", y ); 


Output 


The floor of 2.8 is 2.000000 
The floor of -2.8 is -3.800000 
The ceil of 2.8 is 3.80002 
The ceil of -2.8 is -2.080000 
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Description 


Remarks 


Return Value 
Compatibility 


See Also 


Perform clean-up operations and return without terminating the process. 
#include <process.h> 


void _cexit( void ); 
void _c_exit( void ); 
The _cexit function calls, in LIFO (“last in, first out”) order, the functions registered by 


atexit and onexit. Then the _cexit function flushes all I/O buffers and closes all open files 
before returning. 


The _c_exit function returns to the calling process without processing atexit or onexit 
functions or flushing stream buffers. . 


The behavior of the exit, exit, cexit, and _c_exit functions is described in the following 
list: 


Function Action 


exit Performs complete C library termination procedures, termi- 
nates the process, and exits with the supplied status code 


_exit Performs “quick” C library termination procedures, terminates 
the process, and exits with the supplied status code 


_cexit Performs complete C library termination procedures and re- 
turns to caller, but does not terminate the process 


_c¢ exit _ Performs “quick” C library termination procedures and re- 
turns to caller, but does not terminate the process 
None. 


O ANS! @ DOS WM OS/2 QO UNIX OC XENIX 


abort, atexit, exec functions, exit, onexit, spawn functions, system 
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Description Gets a character string from the console. 

#include <conio.h> Required only for function declarations 

char *cgets( char *buffer ); 

buffer Storage location for data 
Remarks The cgets function reads a string of characters directly from the console and stores the 


Return Value 


Compatibility 


See Also 


Example 


string and its length in the location pointed to by buffer. The buffer argument must be a | 
pointer to a character array. The first element of the array, buffer[0], must contain the maxi- 
mum length (in characters) of the string to be read. The array must contain enough ele- 
ments to hold the string, a terminating null character (’\0’), and two additional bytes. 


The egets function continues to read characters until a carriage-return—line-feed (CR-LF) 
combination is read, or the specified number of characters is read. The string is stored 
starting at str(2]. If a CR-LF combination is read, it is replaced with a null character (°\0’) 
before being stored. The cgets function then stores the actual length of the string in the sec- 
ond array element, buffer[1]. 


Because all DOS editing keys are active when you call egets, pressing F3 repeats the last 
entry. 


The égets function returns a pointer to the start of the string, at buffer[2]. There is no error 
return. 


O ANS! @ DOS WM OS/ OF UNIX OC XENIX 


getch, getche 


/* CGETS.C: This program creates a buffer and initializes the first byte 
* to the size of the buffer - 2. Next, the program accepts an input string 
* using cgets and displays the size and text of that string. 


a 6 


d#FHinclude <conio.h> 
dFinclude <stdio.h> 
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void main() 

{ 
char buffer[82] = { 88 }; /* Maximum characters in first byte */ 
char *resuit; 


printf( "Input line of text, followed by carriage return:\n"); 

result = cgets( buffer ); /* Input a line of text */ 

printf( "\nLine length = %2d\nText = %s\n", buffer{lj, result ); 
} 


Output 


Input line of text, followed by carriage return: 
This is some text 

Line length = 17 

Text = This is some text 
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rr eS PS AI 
Description Chains an interrupt from one handler to another. 

#include <dos.h> 

void _chain_intr( void( interrupt _far *target )()); | 

target Target interrupt routine 


Remarks The _chain_intr routine passes control from one interrupt handler to another. The stack 
and the registers of the first routine are passed to the second, allowing the second routine 
to return as if it had been called directly. 


The _chain_intr routine is generally used when a user-defined interrupt handler begins © 
processing, then chains to the original interrupt handler to finish processing. 


Chaining is one of two techniques, listed below, that can be used to transfer control from a 
new interrupt routine to an old one: 


1. Call _chain_intr with the interrupt routine as an argument. Do this if your routine is 
finished and you want the second interrupt routine to terminate the interrupt call. 


void _interrupt new_int( unsigned _es, unsigned _ds, 
unsigned _di, unsigned _si,... ) 
{ 


Pdi; /* Initial processing here */ 
_chain_intr( old_int ); /* New DI passed to old_int */ 
ah /* This is never executed */ 


} 


2. Call the interrupt routine (after casting it to an interrupt function if necéssary). Do this 
if you need to do further processing after the second interrupt routine finishes. 


void _interrupt new_int( unsigned _es, unsigned _ds, 
unsigned _di, unsigned _si,... ) 


( 


+013 /* Initial processing here */ 
(*old_int)(); /* New DI passed to old_int */ 
_asm mov _di, di /* Put real DI from old_int */ 

/* into _di for return */ 


} 


Note that the real registers set by the old interrupt function are not automatically set to the 
pseudoregisters of the new routine. 
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Use the _chain_intr function when you do not want to replace the default interrupt han- 
dler, but you do need to see its input. An example is a TSR (terminate-and-stay-resident) 
program that checks all keyboard input for a particular “hot key” sequence. 


The _chain_intr function should be used only with C functions that have been declared 
with type interrupt. The interrupt declaration ensures that the procedure’s entry/exit 
sequence is appropriate for an interrupt handler. 


Return Value The _chain_intr function does not return to the caller. 
Compatibility QO ANS! @ DOS OF 0S7 0 UNIX OO) XENIX 


See Also _dos_getvect, dos keep, _dos_setvect 
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Description 


Remarks 


Return Value 


Compatibility 


chdir 


Changes the current working directory. 


#include <direct.h> Required only for function declarations 


#include <errno.h> Required for errno constants 
int chdir( char *dirname ); 
dirname Path name of new working directory 


The chdir function changes the current working directory to the directory specified by 
dirname. The dirname argument must refer to an existing directory. 


This function can change the current working directory on any drive; it cannot be used to 
change the default drive itself. For example, if A: is the default drive and \BIN is the 
current working directory, the following call changes the current working directory for 
drive C: 


chdir("c:\\temp"); 


Notice that you must place two backslashes (\\) in a C string in order to represent a single 
backslash (\); the backslash is the escape character for C strings and therefore requires 
special handling. 


This function call has no apparent immediate effect. However, when the _chdrive function 
is called to change the default drive to C:, the current working directory becomes 
CATEMP. 


In OS/2 protected mode, the current working directory is local to a process rather than 
system-wide. When a process terminates, the current working directory is restored to its 
original value. Under DOS, the new directory set by the program becomes the new current 
working directory. 


The chdir function returns a value of 0 if the working directory is successfully changed. A 
return value of —1 indicates an error, in which case errno is set to ENOENT, indicating 
that the specified path name could not be found. 


O ANS! @ DOS @ OS/2 HE UNIX Wf XENIX 
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See Also _dos_setdrive, mkdir, rmdir, system 


Example 


/* CHGDIR.C: This program uses the chdir function to verify that a 

* given directory exists. Under real mode that directory also becomes 
* the current directory. Under protected mode, it is only the default 
* directory for the current process. , 

*/ 


dHinclude <direct.h> 
dHinclude <stdio.h> 
dHinclude <stdlib.h> 


void main( int argc, char *argv[] ) 
( 
if( chdir( argv{1] ) ) 
printf( "Unable to locate the directory: %s\n", argv[1] ); 
else 
system( “dir *.c" ); 


Output 
CC:\LIBREF] chgdir \tmp 


The volume label in drive C is OS2. 
Directory of C:\TMP 


DUP C 232 4-18-89 11:18a 
TEST C 713 4-87-88 2:49p 
2 File(s) 14155776 bytes free 
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_chdrive 


Description 


Remarks 


Return Value 


Changes the current working drive. 

#include <direct.h> Required only for function declarations 
int chdrive( int drive ); 

drive Number of new working drive 


The _chdrive function changes the current working drive to the drive specified by drive. 
The drive argument uses an integer to specify the new working drive (1=A, 2=B, etc.). 


This function changes only the working drive; the chdir function changes the working 
directory. 


In OS/2 protected mode, the working drive is local to a process rather than system-wide. 
When a process terminates, the working drive is restored to its original value. Under DOS, 
the new drive set by the program becomes the new working drive. 


The _chdrive function returns a value of 0 if the working drive is successfully changed. A 
return value of —1 indicates an error. 


Compatibility O ANS! @ DOS OS? O UNX CO XENIX 

See Also chdir, _dos_setdrive, fullpath, getcwd, _getdrive, mkdir, rmdir, system 
Example 

/* GETDRIVE.C illustrates drive functions including: 

* _getdrive _chdrive _getdcwd 

*/ 


#Hinclude <stdio.h> 
#Hinclude <conio.h> 
#Hinclude <direct.h> 
#Hinclude <stdlib.h> 


_chdrive 
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void main() 
{ 


int ch, drive, curdrive; 
static char path({_MAX_PATH]; 


-/* Save current drive. */ 
curdrive = _getdrive(); 


printf( "Available drives are: \n" ); 


/* If we can switch to the drive, it exists. 


for( drive = 1; drive <= 26; drivet+ ) 
if( !_chdrive( drive ) ) 
printf( "%c: ", drive + ‘A' - 1 ); 


while( 1 ) 
{ 


printf( "\nType drive letter to check or ESC to quit: " )3 


ch = getch(); 
if( ch == 27 ) 


break; 


if( isalpha( ch ) ) 


putch( ch ); 
if( _getdcwd( toupper( ch ) - ‘A’ + 1, path, _MAX_PATH ) != NULL ) 
printf( "\nCurrent directory on that drive is %4s\n", path ); 
} 


/* Restore original drive. This is only necessary for DOS. Under 0S/2 
* the current drive of the calling process is always restored. 


a A 


_chdrive( curdrive ); 


printf( "\n" ); 


Output 

Available drives are: 

A: B: C: 

Type drive letter to check or ESC to quit: q 
Type drive letter to check or ESC to quit: a 


Current directory 


Type drive letter 
Current directory 


Type drive letter 


on 


to 
on 


to 


that drive is A:\ 


check or ESC to quit: c 
that drive is C:\LIBREF 


check or ESC to quit: 


149 chmod 
Description Changes the file-permission settings. 

#include <sys\types.h> 

#include <sys\stat.h> 

#include <errno.h> 

#include <io.h> Required only for function declarations 

int chmod( char *filename, int pmode ); 

filename Path name of existing file 

pmode Permission setting for file 
Remarks The chmod function changes the permission setting of the file specified by filename. The 


Return Value 


permission setting controls read and write access to the file. The constant expression 
pmode contains one or both of the manifest constants S IWRITE and S_IREAD, defined in 
SYS\STAT.H. Any other values for pmode are ignored. When both constants are given, 
they are joined with the bitwise-OR operator (| ). The meaning of the pmode argument is 
as follows: 


Value Meaning 
S_ITWRITE Writing permitted 
S_IREAD Reading permitted 


S IREAD | S_IWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. Under DOS and OS/2, all files are 
readable; it is not possible to give write-only permission. Thus the modes S_TWRITE and 
S_IREAD | S_IWRITE are equivalent. 


The chmod function returns the value 0 if the permission setting is successfully changed. 
A return value of —1 indicates an error; in this case, errno is set to ENOENT, indicating 
that the specified file could not be found. 
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Compatibility O ANS! @ DOS # OS/2 WM UNIX @ XENIX 


See Also access, creat, fstat, open, stat 


Example 


/* CHMOD.C: This program uses chmod to change the mode of a file to 
* read-only. It then attempts to modify the file. 
*/ 


' d#include <sys\types.h> 
#Hinclude <sys\stat.h> 
#Hinclude <io.h> 
d#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 


void main() 
{ 
/* Make file read-only: */ 
if( chmod( "“CHMOD.C", S_IREAD-) == -1 ) 
perror( "File not found\n" ); 
else 
printf( "Mode changed to read-only\n" ); 
system( "echo /* End of file */ >> CHMOD.C" ); 


/* Change back to read/write: */ 

if( chmod( "CHMOD.C", S_IWRITE ) == -1 ) 
perror( "File not found\n" ); 

else 
printf( "Mode changed to read/write\n" ); 


Output 


Mode changed to read-only 
Access denied 
Mode changed to read/write 
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chsize 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Changes the file size. 


#include <io.h> Required only for function declarations 


#include <errno.h> 
int chsize( int handle, long size ); 


handle Handle referring to open file 


size New length of file in bytes 


The chsize function extends or truncates the file associated with handle to the length 
specified by size. The file must be open in a mode that permits writing. Null characters 
(°\0’) are appended if the file is extended. If the file is truncated, all data from the end of 
the shortened file to the original length of the file is lost. 


In DOS, the directory update is done when a file is closed. Consequently, while a program 
is running, requests to determine the amount of free disk space may receive inaccurate 
results. 


The chsize function returns the value 0 if the file size is successfully changed. A return 
value of —1 indicates an error, and errno is set to one of the following values: 


Value Meaning 

EACCES Specified file is locked against access (OS/2 and DOS 
versions 3.0 and later only). 

EBADF Specified file is read-only or an invalid file handle. 

ENOSPC No space is left on device. 


CO ANS! @ DOS WM OS/2 WM UNIX fi XENIX 


close, creat, open 


/* CHSIZE.C: This program uses filelength to report the size of a 
* file before and after modifying it with chsize. 


mf 
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dHinclude <io.h> 
dHinclude <fcnt1l.h> 
dHinclude <sys\types.h> 
#include <sys\stat.h> 
#Hinclude <stdio.h> 


void main() 
{ * 
int fh, result; 
unsigned int nbytes = BUFSIZ; 


/* Open a file */ 
if( (fh = open( "data", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 ) 
( 
printf( "File length before: %ld\n", filelength( fh ) ); 
if( chsize( fh, 329678 ) == @ ) 
printf( "Size successfully changed\n" ); 
else 
printf( "Problem in changing the size\n" ); 
printf( "File length after: %1ld\n", filelength( fh ) ); 
close( fh ); 


Output 


File length before: @ 
Size successfully changed 
File length after: 329678 
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Description Gets and clears the floating-point status word. 
#include <float.h> 
unsigned int _clear87( void ); 


Remarks The _clear87 function gets and clears the floating-point status word. The floating-point sta- 
tus word is a combination of the 8087/80287 status word and other conditions detected by 
the 8087/80287 exception handler, such as floating-point stack overflow and underflow. 


Return Value The bits in the value returned indicate the floating-point status. See the FLOAT.H include 
file for a complete definition of the bits returned by _clear87. 


Many of the math library functions modify the 8087/80287 status word, with unpredict- 
able results. Return values from _clear87 and _status87 become more reliable as fewer 
floating-point operations are performed between known states of the floating-point status 


word. 
Compatibility O ANSi| M@ DOS HM OS2 QO UNIX O XENI 
See Also _control87, _status87 


Example 


/* CLEAR87.C: This program creates various floating-point problems, 
* then uses _clear87 to report on these problems. 
oa 


fHinclude <stdio.h> 
dFinclude <float.h> 


void main() 

( 
double a = le-4@, b; 
float x, y; 


printf( “Status: %.4x - clear\n", _clear87() ); 
/* Store into y is inexact and underflows: */ 


y= a; 
printf( "Status: %.4x - inexact, underflow\n", _clear87() ); 
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/* y is denormal: */ 

Demys 

printf( "Status: %.4x - denormal\n", _clear87() ); 
} 


Output 


Status: Q@@@8 - clear 
Status: 0030 - inexact, underflow 
Status: 9@@2 - denormal 
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Description Resets the error indicator for a stream. 

#include <stdio.h> 

void clearerr( FILE *stream ); 

stream Pointer to FILE structure 


Remarks The clearerr function resets the error indicator and end-of-file indicator for stream. Error 
indicators are not automatically cleared; once the error indicator for a specified stream is 
set, operations on that stream continue to return an error value until clearerr, fseek, 
fsetpos, or rewind is called. 


Return Value None. 

Compatibility MANS! @ DOS WM OS/2 HB UNIX” ft XENIX 
See Also eof, feof, ferror, perror 

Example 


/* CLEARERR.C: This program creates an error on the standard input 
* stream, then clears it so that future reads won't fail. 
*/ : 


dHinclude <stdio.h> 


void main() 
{ 


int c; 


/* Create an error by writing to standard input. */ 
putc( ‘c', stdin ); 
if( ferror( stdin ) ) 
{ 
perror( “Write error" ); 
clearerr( stdin ); 
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/* See if read causes an error. */ 
printf( "Will input cause an error? " ); 
c = getc( stdin ); 
if( ferror( stdin ) ) 
{ 

perror( "Read error” ); 

clearerr( stdin ); 


Output 


Write error: Error @ 
Will input cause an error? n 
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_clearscreen 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


/* <CLRSERN Cy 


Clears the specified area of the screen. 
#include <graph.h> 

void far _clearscreen( short area ); 
area Target area 


The _clearscreen function erases the target area, filling it with the current background 
color. The area parameter can be one of the following manifest constants (defined in 
GRAPH.H): 


Constant Action 

_GCLEARSCREEN Clears and fills the entire screen 

_GVIEWPORT Clears and fills only within the current view port 
_GWINDOW Clears and fills only within the current text window 
None. 
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_getbkcolor, _setbkcolor 


dFinclude <conio.h> 
dHinclude <graph.h> 
d#Finclude <stdlib.h> 


void main() 


{ 


short xhalf, yhalf, xquar, yquar; 
struct videoconfig vc; 
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/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1); 


_getvideoconfig( &vc ); 


xhalf = vc.numxpixels / 2; 
yhalf = vc.numypixels / 2; 
xquar = xhalf / 2; 
yquar = yhalf / 2; 


_setviewport( @, @, xhalf - 1, yhalf - 1 ); 

_rectangle( _GBORDER, @, @, xhalf - 1, yhalf - 1 ); 

_—ellipse( _GFILLINTERIOR, xquar / 4, yquar / 4, 

xhalf - (xquar / 4), yhalf - (yquar / 4) ); 
getch(); 
_clearscreen( _GVIEWPORT ); 


getch(); 
_setvideomode( _DEFAULTMODE ); 
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Description Calculates the time used by the calling process. 
#include <time.h> 
clock_t clock( void ); 


Remarks The clock function tells how much processor time has been used by the calling process. 
The time in seconds is approximated by dividing the clock return value by the value of the 
CLOCKS_PER_SEC constant. 


In other words, the clock function returns the number of processor timer ticks that have 
elapsed. A timer tick is approximately equal to 1/CLOCKS_PER_SEC seconds. 


Return Value The clock function returns the product of the time in seconds and the value of the 
CLOCKS _PER_SEC constant. If the processor time is not available, the function returns 
the value —1, cast as clock_t. 


Compatibility MANS) @ DOS mMoOS2 OUNKX O XENI 


In both DOS and OS/2, clock returns the time elapsed since the process started. This may 
not be equal to the actual processor time used by the process. 


In previous versions of Microsoft C, the CLOCKS_PER_SEC constant was called 
CLK_TCK. 


See Also difftime, time 


Example 


/* CLOCK.C: This example prompts for how long the program is to run and 
* then continuously displays the elapsed time for that period. 
ay 


dHinclude <stdio.h> 
dFinclude <stdlib.h> 
dHinclude <time.h> 


void sleep( clock_t wait ); 


void main() 

{ 
long i = 600000L; 
clock_t start, finish; 
double duration; 
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/* Delay for a specified time. */ 
printf( “Delay for three seconds\n" ); 
sleep( (clock_t)3 * CLOCKS_PER_SEC ); 
printf( "Done!\n" ); 


/* Measure the duration of an event. */ 
printf( "Time to do 41d empty loops is ", i ); 
start = clock(); 

while( i-- ) 


finish = clock(); 
duration = (double)(finish - start) / CLOCKS_PER_SEC; 
printf( "%2.1f seconds\n", duration ); 

) 


/* Pauses for a specified number of microseconds. */ 
void sleep( clock_t wait ) 
( 

clock_t goal; 


goal = wait + clock();. 
while( goal > clock() ) 


Output 


Delay for five seconds 
Done! 
Time to do 980808 empty loops is 2.0 seconds 
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Description Closes a file. 


#include <io.h> Required only for function declarations 


#include <errno.h> 


int close( int handle ); 


handle Handle referring to open file 
Remarks The close function closes the file associated with handle. 
Return Value The close function returns 0 if the file was successfully closed. A return value of —1 indi- 


cates an error, and errno is set to EBADF, indicating an invalid file-handle argument. 


Compatibility CO ANS! @ DOS #8 OS/2 MW UNIX Wf XENIX 
See Also chsize, creat, dup, dup2, open, unlink 
Example 


/* OPEN.C: This program uses open to open a file named OPEN.C for input 
* and a file named OPEN.OUT for output. The files are then closed. 
ba 


#include <fcntl.h> 
#Hinclude <sys\types.h> 
#Hinclude <sys\stat.h> 
#Finclude <io.h> 
dHinclude <stdio.h> 


void main() 
{ 
int fhl, fh2; 
fhl = open( "OPEN.C", O_RDONLY ); 
if( fhl == -1 ) 
perror( “open failed on input file” ); 
else 
{ 
printf( “open succeeded on input file\n" ); 
close( fhl ); 
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fh2 = open( "OPEN.OUT", O_WRONLY | O_CREAT, S_IREAD | S_IWRITE ); 
if( fh2 == -1 ) 

perror( “open failed on output file” ); 
else 


{ 
printf( "open succeeded on output file\n" ); 
close( fh2 ); 


Output 


open succeeded on input file 
open succeeded on output file 
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_control87 


Description 


Remarks 


Gets and sets the floating-point control word. 
#include <float.h> 
unsigned int _control87( unsigned int new, unsigned int mask ); 


new New control-word bit values 


mask Mask for new control-word bits to set 


The _control87 function gets and sets the floating-point control word. The floating-point 
control word allows the program to change the precision, rounding, and infinity modes in 
the floating-point-math package. Floating-point exceptions can also be masked or un- 
masked using the _control87 function. — | 


If the value for mask is equal to 0, then _control87 gets the floating-point control word. If 
mask is nonzero, then a new value for the control word is set in the following manner: for 
any bit that is on (equal to 1) in mask, the corresponding bit in new is used to update the 
control word. To put it another way, 


fpcntrl = ((fpcntrl & ~mask) | (new & mask)) 
where fpcntr1 is the floating-point control word. 


The possible values for the mask constant (mask) and new control values (new) are shown 
in Table R.1. 


Table R.1 Hex Values 


Mask Hex Value Constant Hex Value 
MCW_EM 0x003F 
(Interrupt 
exception) 
EM_INVALID 0x0001 


EM_DENORMAL 0x0002 
EM_ZERODIVIDE — 0x0004 
EM_OVERFLOW 0x0008 
EM_UNDERFLOW __ 0x0010 
EM_INEXACT 0x0020 
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Table R.1 = (continued) 


Mask Hex Value Constant Hex Value 

MCW_IC 0x1000 

(Infinity 

control) 
IC_AFFINE 0x1000 
IC_PROJECTIVE 0x0000 

MCW_RC 0x0C00 

(Rounding 

control) 
RC_CHOP 0x0C00 
RC_UP 0x0800 
RC_DOWN 0x0400 
RC_NEAR 0x0000 

MCW_PC 0x0300 

(Precision 

control) 
PC_24 (24 bits) 0x0000 
PC_53 (53 bits) 0x0200 
PC_64 (64 bits) 0x0300 

Return Value The bits in the value returned indicate the floating-point control state. See the FLOAT.H 


include file for a complete definition of the bits returned by _control87. 


Compatibility O ANS| @ DOS #8 OS 


See Also _clear87, _status87 


Example 


/* CNTRL87.C: This program uses _control87 to output the control word, 
* set the precision to 24 bits, and reset the status to the default. 


it 


#Hinclude <stdio.h> 
#Hinclude <float.h> 


O UNIX OC XENIX 


165 | _control87 


void main() 
{ 
double a = @.1; 


/* Show original control word and do calculation. */ 
printf( “Original: @x%.4x\n", _control87( 9, @ ) ); 
printf( "Z1.1f * @1.1f = %.15e\n", a, a, a * a ); 


/* Set precision to 24 bits and recalculate. */ 
printf( "24-bit: Qx%.4x\n", _control87( PC_24, MCW_PC ) ); 
printf( "Sl.1f * Z1.1f = %.15e\n", a, a, a * a ); 


/* Restore to default and recalculate. */ 
printf( “Default: @x%.4x\n", _control87( CW_DEFAULT, @xffff ) ); 
printf( "“%1.1f * @1.1f = %.15e\n", a, a, a* a )3 


Output 


Original: @x1332 
0.1 * B.1 = 1.800BGH0BG0BB000e-202 
24-bit: 8x1332 
Q.1 * @.1 = 9.999999776482582e-003 
Default: @x1932 
G.1 * 0.1 = 1.000BGB000000000e-002 
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Description Calculate the cosine (cos and cosl) or hyperbolic cosine (cosh and coshl). 
#include <math.h> 


double cos( double <x ); 
double cosh( double x ); 
long double cosl( long double x ); 


long double coshI( long double x ); 
x Angle in radians 


Remarks The cos and cosh functions return the cosine and hyperbolic cosine, respectively, of x. 


The cosl and coshl functions are the 80-bit counterparts and use the 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long double 
functions for more details on this data type. 


Return Value If x is large, a partial loss of significance in the result may occur in a call to cos, in which 
case the function generates a PLOSS error. If x is so large that significance is completely 
lost, cos prints a TLOSS message to stderr and returns 0. In both cases, errno is set to 
ERANGE. 


If the result is too large in a cosh call, the function returns HUGE_VAL and sets errno to 
ERANGE. 


Compatibility cos, cosh 
MANS! @ DOS WH OS/2 UNIX’ @) XENIX 


cosl, coshl 


O ANS! M@ DOS WM OS/2 QO UNIX O XENIX 
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See Also - acos functions, asin functions, atan functions, matherr, sin functions, tan functions 


Example 


/* SINCOS.C: This program displays the sine, hyperbolic sine, cosine, 
* and hyperbolic cosine of pi / 2. 
J 


dHinclude <math.h> 
dtinclude <stdio.h> 


void main() 

{ 
double pi = 3.1415926535; 
double x, y; 


x= pi / 2; 

y = sin( x ); 

printf( “sin( @f ) = 4f\n", x, y ); 
y = sinh( x ); 

printf( “sinh( 2f ) = 4f\n",x, y ); 
y = cos( x ); 

printf( “cos( %f ) = 4f\n", x, y ); 
y = cosh( x ); 

printf( “cosh( 4f ) = @f\n",x, y ); 


Output 


sin( 1.570796 ) = 1.800800 
sinh( 1.578796 ) = 2.381299 
cos( 1.570796 ) = 8.800000 
cosh( 1.578796 ) = 2.599178 
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a a a a a a a 
Description Formats and prints to the console. 
#include <conio.h> Required only for function declarations 


int cprintf( char *format [, argument] ... ); 


format Format control string 
argument Optional arguments 
Remarks The cprintf function formats and prints a series of characters and values directly to the 


console, using the putch function to output characters. Each argument (if any) is con- 
verted and output according to the corresponding format specification in format. The for- 
mat has the same form and function as the format argument for the printf function; see 
printf for a description of the format and arguments. 


Note that unlike the fprintf, printf, and sprintf functions, cprintf does not translate line- 
feed characters into carriage-return—line-feed combinations on output. 


Return Value The cprintf function returns the number of characters printed. 
Compatibility O ANS! @ DOS MOS O UNX Oj XENIX 


See Also cscanf, fprintf, printf, sprintf, vprintf 


Example 


/* CPRINTF.C: This program displays some variables to the console. */ 
#Hinclude <conio.h> 


void main() 
{ 


int j = -16, h = 29; 
unsigned u = 62511; 
char c= 'A'; 


char s(t] = "Test"; 
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/* Note that console output does not translate \n as 
* standard output’ does. Use \r\n instead. 

=f 

cprintf( “4d %.4x %u %c &s\r\n", i, h, u, c, Ss )3 


Output 


-16 @@1d 62511 A Test 
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Description Puts a string to the console. 
#include <conio.h> Required only for function declarations 


int cputs( char *string );__ 


string Output string 
’ Remarks The cputs function writes the null-terminated string pointed to by string directly to the con- 
sole. Note that a carriage-return—line-feed (CR-LF) combination is not automatically ap- 
pended to the string. 
Return Value If successful, cputs returns a 0, If the function fails, it returns a nonzero value. 


Compatibility O ANS| m DOS mOS2 CO UNIX O XENIX 


See Also putch 


Example 
/* CPUTS.C: This program first displays a string to the console. */ 


#Hinclude <conio.h> 


void main() 

{ 
/* String to print at console. Note the \r (return) character. */ 
char *buffer = "Hello world (courtesy of cputs)!\r\n"; 


cputs( buffer ); 


Output 


Hello world (courtesy of cputs)! 
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Description Creates a new file. 

#include <sys\types.h> 

#include <sys\stat.h> ) 

#include <errno.h> 

#include <io.h> Required only for function declarations 

int creat( char *filename, int pmode ); | 

filename Path name of new file 

pmode Permission setting 
Remarks The creat function either creates a new file or opens and truncates an existing file. If the 


file specified by filename does not exist, a new file is created with the given permission set- 
ting and is opened for writing. If the file already exists and its permission setting allows 
writing, creat truncates the file to length 0, destroying the previous contents, and opens it 
for writing. 


The permission setting, pmode, applies to newly created files only. The new file receives 
the specified permission setting after it is closed for the first time. The integer expression 
pmode contains one or both of the manifest constants S IWRITE and S_IREAD, defined in 
SYS\STAT.H. When both of the constants are given, they are joined with the bitwise-OR 
operator (|). The pmode argument is set to one of the following values: 


Value Meaning 
S_IWRITE Writing permitted 
S_ TREAD Reading permitted 


S IREAD|S_IWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. Under DOS and OS/2, it is not 
possible to give write-only permission. Thus, the S ITWRITE and S IREAD | S TWRITE 
modes are equivalent. Under DOS versions 3.0 and later, files opened using creat are al- 
ways opened in compatibility mode (see sopen). 


The creat function applies the current file-permission mask to pmode before setting the 
permissions (see umask). 


Note that the creat routine is provided primarily for compatibility with previous libraries. 
A call to open with O_CREAT and O_TRUNC in the oflag argument is equivalent to creat 
and is preferable for new code. 
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Return Value If successful, creat returns a handle for the created file. Otherwise, it returns —1 and sets 
errno to one of the following constants: 


Value Meaning — 

EACCES Path name specifies an existing read-only file or specifies a 
directory instead of a file 

EMFILE No more handles available (too many open files) 

ENOENT Path name not found 


Compatibility O ANS| @ DOS # OS/2 UNIX” @ XENIX 


See Also chmod, chsize, close, dup, dup2, open, sopen, umask 


Example 


/*. CREAT.C: This program uses creat to create the file (or truncate the 
* existing file) named data and open it for writing. 
*/ : 


#Hinclude <sys\types.h> 
#Hinclude <sys\stat.h> 
#Hinclude <io.h> 
#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 


void main() 
{ 
int fh; 


fh = creat( "data", S_IREAD | S_IWRITE ); 
if( fh == -1 ) 

perror( "Couldn't create data file" ); 
else 
{ ; 
printf( "Created data file.\n" ); 
close( fh ); 


Output 


Created data file. 
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cscant 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Reads formatted data from the console. 
#include <conio.h> Required only for function declarations 
int cscanf( char *format [[, argument] ... )3 


format Format-control string 


argument Optional arguments 


The cscanf function reads data directly from the console into the locations given by 
argument. The getche function is used to read characters. Each optional argument must be 
a pointer to a variable with a type that corresponds to a type specifier in format. The for- 
mat controls the interpretation of the input fields and has the same form and function as the 
format argument for the scanf function; see scanf for a description of format. 


While cscanf normally echoes the input character, it will not do so if the last call was to 
ungetch. 


The cscanf function returns the number of fields that were successfully converted and as- 
signed. The return value does not include fields that were read but not assigned. 


The return value is EOF for an attempt to read at end-of-file. This may occur when key- 
board input is redirected at the operating system command-line level. A return value of 0 
means that no fields were assigned. 


O ANS! @ DOS MOS/ O UNIX O XENIX 


cprintf, fscanf, scanf, sscanf 


/* CSCANF.C: This program prompts for a string and uses cscanf to read 
* in the response. Then cscanf returns the number of items matched, 
* and the program displays that number. 


a 


#Hinclude <stdio.h> 
dFHinclude <conio.h> 
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void main() 
{ 
int result, i[3]; 


cprintf( "Enter three integers: "); 
result = cscanf( "%i %i %i", &i[@], &if1), &if2] ); 
cprintf( "\r\nYou entered " ); 
while( result-- ) 
cprintf( "%i ", ifresult] ); 
cprintf( "\r\n" ); 


Output 


Enter three integers: 34 43 987k 
You entered 987 43 34 
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Description Converts a time stored as a time_t value to a character string. 
#include <time.h> Required only for function declarations 
char *ctime( const time_t *timer ); 
timer Pointer to stored time 


Remarks The ctime function converts a time stored as a time_t value to a character string. The 
timer value is usually obtained from a call to time, which returns the number of seconds 
elapsed since 00:00:00 Greenwich mean time, January |, 1970. 


The string result produced by ctime contains exactly 26 characters and has the form of the 
following example: 


Wed Jan 02 02:03:55 198@\n\0 


A 24-hour clock is used. All fields have a constant width. The newline character (\n) and 
the null character (’\0’) occupy the last two positions of the string. 


Calls to the ctime function modify the single statically allocated buffer used by the 
gmtime and the localtime functions. Each call to one of these routines destroys the result 
of the previous call. The ctime function also shares a static buffer with the asctime func- 
tion. Thus, a call to ctime destroys the results of any previous call to asctime, localtime, 
or gmtime. 


Return Value The ctime function returns a pointer to the character string result. If time represents a date 
before 1980, ctime returns NULL. 


Compatibility MANS! @ DOS #8 OS/2 UNIX’ = XENIX 
See Also asctime, ftime, gmtime, localtime, time 
Example 


/* ASCTIME.C: This program places the system time in the long integer aclock, 
* translates it into the structure newtime and then converts it to 

* string form for output, using the asctime function. 

a | 


#include <time.h> i 
#include <stdio.h> 
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struct tm *newtime; 
time_t aclock; 


void main() 


{ 
time( &aclock ); /* Get time in seconds. */ 
newtime = localtime( &aclock ); /* Convert time to struct tm form. */ 
/* Print local time as a string. */ 
printf( "The current date and time are: %s\n", asctime( newtime ) ); 
} . 
Output 


The current date and time are: Thu Jun 15 96:57:59 1989 
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Description Waits until the child process terminates. 

#include <process.h> 

int cwait( int *termstat, int procid, int action ); 

termstat Address for termination status code 

procid Process ID of child 

action Action code 
Remarks The cwait function suspends the calling process until the specified child process 


terminates. 


If not NULL, termstat points to a buffer where cwait will place the termination-status word 
and the return code of the terminated child process. 


The termination-status word indicates whether or not the child process terminated nor- 
mally by calling the OS/2 DosExit function. (Programs that terminate with exit or by 
“falling off the end of main” use DosExit internally.) If the process did terminate nor- 
mally, the low-order and high-order bytes of the termination-status word are as follows: 


Byte Contents 


High order Contains the low-order byte of the result code that the child 
code passed to DosExit. The DosExit function is called if the 
child process called exit or _exit, returned from main, or 
reached the end of main. The low-order byte of the result 
code is either the low-order byte of the argument to _ exit or 
exit, the low-order byte of the return value from main, or a 
random value if the child process reached the end of main. 


Low order 0 (normal termination). 
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Return Value 


If the child process terminates without calling DosExit, the high-order and low-order bytes 
of the termination-status word are as follows: 


Byte Contents 
High order 0 
Low order Termination code from DosCWait: 
Code Meaning 
1 Hard-error abort 
2 Trap operation 
3 SIGTERM signal not intercepted 


The procid argument specifies which child-process termination to wait for. This value is re- 
turned by the call to the spawn function that started the child process. If the specified child 
process terminates before cwait is called, the function returns immediately. 


The action argument specifies when the parent process resumes execution, as shown in the 
following list: 


Value Meaning 
WAIT_CHILD The parent process waits until the specified child process has 
ended. 


WAIT_GRANDCHILD The parent process waits until the specified child process and 
all child processes of that child process have ended. 


The WAIT_CHILD and WAIT_GRANDCHILD action codes are defined in PROCESS.H. 
If the cwait function returns after normal termination of the child process, it returns the 
child’s process ID. 


If the cwait function returns after abnormal termination of the child process, it returns —1 
and sets errno to EINTR. 


Otherwise, the cwait function returns —1 immediately and sets errno to one of the follow- 
ing error codes: 


Value Meaning 
ECHILD No child process exists, or invalid process ID 
EINVAL Invalid action code 
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Compatibility O ANS| O DOS moOS2 O UNIX O XENI 


Note that the OS/2 DosExit function allows programs to return a 16-bit result code. How- 
ever, the wait and cwait functions return only the low-order byte of that result code. 


See Also exit, exit, spawn functions, wait 


Example 


/* CWAIT.C: This program launches several child processes and Males 
* for a specified process to finish. 
sa f 


dtdefine INCL_NOPM 

#tdefine INCL_NOCOMMON 

itdefine INCL_DOSPROCESS 

#Hinclude <os2.h> /* DosSleep */ 
#Hinclude <process.h> /* cwait ca 
#Hinclude <stdlib.h> 

#Hinclude <stdio.h> 

dHinclude <time.h> 


/* Macro to get a random integer within a specified range */ 
#define getrandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) + (min)) 


struct CHILD 
{ 
int pid; 
char name{1@]; 
} child(l4] = { { @, "Ann" }, ( @, "Beth" J}, { @, “Carl" J}, { @, "Dave" } }; 


void main( int argc, char *argv[] ) 
{ 
int termstat, pid, c, tmp; 


srand( (unsigned)time( NULL ) ); /* Seed randomizer */ 
/* Tf no arguments, this is the parent. */ 
if( arge == 1 ) 
{ 

/* Spawn children in numeric order. */ 

for( c = @3; c < 4; ctt+ ) 

child{c].pid = spawnl( P_NOWAIT, argv{@], argv(@], 
child{c].name, NULL ); 
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J 
/* 1 


else 
{ 


Output 


/* Wait for randomly specified child, and respond when done. */ 
c = getrandom( 9, 3 ); 

printf( “Come here, %s\n", child[c].name ); 

cwait( &termstat, child£ic].pid, WAIT_CHILD ); 

printf( "Thank you, %s\n", child{c].name ); 


f there are arguments, this must be a child. */ 


/* Delay for a period determined by process number. */ 
DosSleep( (argv[1][@] - 'A' + 1) * 10@@L ); 
printf( "Hi, dad. It's 4s.\n", argv[1] ); 


Come here, Carl 


Hi, dad. 
Hi, dad. 
Hi, dad. 


It's Ann. 
It's Beth. 
It's Carl. 


Thank you, Carl 


Hi, dad. 


It's Dave. 
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_dieeetomsbin, dmsbintoieee 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Convert between IEEE double value and Microsoft (MS) binary double value. 
#include <math.h> 


int dieeetomsbin( double *src8, double *dst8 ); 


int dmsbintoieee( double *src8, double *dst8 ); 


src8 Buffer containing value to convert 


dst8 Buffer to store converted value 


The dieeetomsbin routine converts a double-precision number in IEEE (Institute of 
Electrical and Electronic Engineers) format to Microsoft (MS) binary format. The routine 
dmsbintoieee converts a double-precision number in MS binary format to IEEE format. 


These routines allow C programs (which store floating-point numbers in the TEEE format) 
to use numeric data in random-access data files created with those versions of Microsoft 
BASIC that store floating-point numbers in MS binary format, and vice versa. 


The argument src8 is a pointer to the double value to be converted. The result is stored at 
the location given by dst8. 


These routines do not handle IEEE NANSs (“not a number”) and infinities. IEEE denormals 
are treated as 0 in the conversions. 


These functions return 0 if the conversion is successful and 1 if the conversion causes an 
overflow. 


O ANS! @ DOS WM OS/?2 O UNIX OC XENIX 


fieeetomsbin, fmsbintoieee 
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Description Finds the difference between two times. 
#include <time.h> Required only for function declarations 


double difftime( time_t timer/, time_t timer0 ); 


timerO Beginning time 
timer1 Ending time 
Remarks The difftime function computes the difference between the supplied time values, timer0 


and timer]. 


Return Value The difftime function returns, in seconds, the elapsed time from timer0 to timer]. The 
value returned is a double-precision number. 


Compatibility MANS! M@ DOS M@ OS/2 MW UNIX MB XENIX 


See Also time 


Example 


/* DIFFTIME.C: This program calculates the amount of time needed to 
* do a floating-point multiply 50000 times. 
*/ 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <time.h> 


void main() 

{ 
time_t start, finish; 
unsigned loop; 
double result, elapsed_time; 


printf( "This program will do a floating point multiply 58800 times\n" ); 
printf( "Working...\n" ); 


time( &start ); 

for( loop = 8; loop < 58@Q@00L; loop++ ) 
result = 3.63 * 5.27; 

time( &finish ); 
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elapsed_time = difftime( finish, start ); 
printf( "\nProgram takes %6.2f seconds.\n", elapsed_time ); 


} 
Output 


This program will do a floating point multiply 50900 times 
Working... 


Program takes 4.00 seconds. 
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Se a a a a a a a a a ee ee | 
Description Disables interrupts. 

#include <dos.h> 

void _disable( void ); 


Remarks — The disable routine disables interrupts by executing an 8086 CLI machine instruction. 
Use _disable before modifying an interrupt vector. 


Return Value None. 
Compatibility . O ANS! #@ DOS OF OS/2 OO UNIX O XENIX 


See Also _enable 


185 _displaycursor 


Description Sets the cursor toggle for graphics functions. 
#include <graph.h> 
short far displaycursor( short toggle ); 
toggle Cursor state 


Remarks Upon entry into each graphic routine, the screen cursor is turned off. The _displaycursor 
function determines whether the cursor will be turned back on when programs exit graphic 
routines. If toggle is set to_GCURSORON, the cursor will be restored on exit. If toggle is 
set to_GCURSOROFF, the cursor will be left off. 


Return Value The function returns the previous value of toggle. There is no error return. 
Compatibility O ANS! @ DOS’ # OS/2 | O UNIX O XENIX 

See Also _gettextcursor, _settextcursor 

Example 


/* DISCURS.C: This program changes the cursor shape using _gettextcursor 
* and _settextcursor, and hides the cursor using _displaycursor. 
a 


dHinclude <conio.h> 
#Hinclude <graph.h> 


void main() 
{ 
short oldcursor; 
short newcursor = Qx@Q7; /* Full block cursor */ 


/* Save old cursor shape and make sure cursor is on */ 
oldcursor = _gettextcursor(); 

_Clearscreen( _GCLEARSCREEN ); 

_displaycursor( _GCURSORON ); 

_outtext( “\nOld cursor shape: " );. 

getch(); 


/* Change cursor shape */ 

_outtext( "\nNew cursor shape: " ); 
_settextcursor( newcursor ); 
getch(); 
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/* Restore original cursor shape */ 
_outtext( "\n" ); 
_settextcursor( oldcursor ); 

} 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


div 
Computes the quotient and the remainder of two integer values. 
#include <stdlib.h> 


div_t div( int numer, int denom ); 


numer Numerator 


denom : Denominator 


The div function divides numer by denom, computing the quotient and the remainder. The 
div_t structure contains the following elements: 


Element Description 
int quot Quotient 


int rem Remainder 


The sign of the quotient is the same as that of the mathematical quotient. Its absolute value 
is the largest integer that is less than the absolute value of the mathematical quotient. If the 
denominator is 0, the program will terminate with an error message. 


The div function returns a structure of type div_t, comprising both the quotient and the re- 
mainder. The structure is defined in STDLIB.H. 


MANS! H@ DOS HW OS/2 O UNIX O XENIX 


Idiv 


/* DIV.C: This example takes two integers as command-line arguments and 
* displays the results of the integer division. This program accepts 

* two arguments on the command line following the program name, then 

* calls div to divide the first argument by the second. Finally, 

* jt prints the structure members quot and rem. 


fHinclude <stdlib.h> 
dFinclude <stdio.h> 
#Hinclude <math.h> 
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void main( int argc, char *argv[] ) 
{ 

int x,y; 

div_t div_result; 


x = atoi( argv(1] ); 
y = atoi( argv(2] ); 


printf( "x is 4d, y is @d\n", x, y )3 

div_result = div( x, y ); 

printf( “The quotient is %d, and the remainder is %d\n", 
div_result.quot, div_result.rem ); 


Output 


CC:\LIBREF] div 876 13 
x is 876, y is 13 
The quotient is 67, and the remainder is 5 


189 _dos_allocmem 
Description Allocates a block of memory, using DOS service 0x48. 

#include <dos.h> 

#include <errno.h> 

unsigned dos_allocmem( unsigned size, unsigned “seg ); 

size Block size to allocate 

seg Return buffer for segment descriptor 
Remarks The _dos_allocmem function uses DOS service 0x48 to allocate a block of memory size 


Return Value 


paragraphs long. (A paragraph is 16 bytes.) Allocated blocks are always paragraph 
aligned. The segment descriptor for the initial segment of the new block is returned in the 
word that seg points to. If the request cannot be satisfied, the maximum possible size (in 
paragraphs) is returned in this word instead. 


If successful, the _dos_allocmem returns 0. Otherwise, it returns the DOS error code and 
sets errno to ENOMEM,, indicating insufficient memory or invalid arena (memory area) — 
headers. 


Compatibility O ANS! M@ DOS OF Oos2 QO UNIX OC XENIX 

See Also alloca, calloc functions, _dos_freemem, _dos_setblock, halloc, malloc functions 
Example 

/* DALOCMEM.C: This program allocates 20 paragraphs of memory, increases 

* the allocation to 49 paragraphs, and then frees the memory space. : 
*/ 


#Hinclude <dos.h> 
dHinclude <stdio.h> 


void main() 


{ 


unsigned segment; 
unsigned maxsize; 
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/* Allocate 28 paragraphs */ 

if( _dos_allocmem( 20, &segment ) != @ ) 
printf( "allocation failed\n" ); 

else 
printf( "allocation successful\n" ); 


/* Increase allocation to 48 paragraphs */ 

if( _dos_setblock( 40, segment, &maxsize ) != Q@ ) 
printf( “allocation increase failed\n" ); 

else 
printf( “allocation increase successful\n" ); 


/* free memory */ 
if( _dos_freemem( segment ) != @ ) 
printf( “free memory failed\n" ); 
else 
printf( "free memory successful\n" ); 


Output 


allocation successful 
allocation increase successful 
free memory successful 
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Description Closes a file using system call INT 0x3E. 


#include <dos.h> . 


#include <errno.h> 
unsigned _dos_close( int handle ); 
handle . Target file handle 


Remarks The _dos_close function uses system call 0x3E to close the file indicated by handle. The 
file’s handle argument is returned by the call that created or last opened the file. 


Return Value The function returns 0 if successful. Otherwise, it returns the DOS error code and sets 
errno to EBADF, indicating an invalid file handle. 


Do not use the DOS interface I/O routines with the console, low-level, or stream I/O 


routines. 
Compatibility O ANS! @ DOS OF O0S/72 O UNIX QO XENIX 
See Also close, creat, _dos_creat functions, dos_open, dos read, _dos_write, dup, open 


Example 
/* DOPEN.C: This program uses DOS 1/0 functions to open and close a file. */ 


#Finclude <fcnt].h> 
dHinclude <stdio.h> 
#FHinclude <dos.h> 


void main() 
{ 
int fh; 


/* Open file with _dos_open function */ 
if( _dos_open( “datal", O_RDONLY, &fh ) !=@ ) 
perror( “Open failed on input file\n" ); 
else 
printf( "Open succeeded on input file\n" ); 
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/* Close file with _dos_close function */ 
if( _dos_close( fh ) !=@ ) 
perror( "Close failed\n" ); 


else 
printf( "File successfully closed\n" ); 


Output 


Open succeeded on input file 
File successfully closed 


193 _dos_creat Functions 
Description Create a new file. 

#include <dos.h> 

#include <errno.h> 

unsigned _dos_creat( char “filename, unsigned attrib, int *handle ); 

unsigned _dos_creatnew( char *filename, unsigned attrib, int *handle ); 

filename File path name 

attrib File attributes 

handle Handle return buffer 
Remarks The _dos_creat and _dos_creatnew routines create and open a new file named filename; 


Return Value 


this new file has the access attributes specified in the attrib argument. The new file’s 
handle is copied into the integer location pointed to by handle. The file is opened for both 
read and write access. If file sharing is installed, the file is opened in compatibility mode. 


The _dos_creat routine uses system call INT 0x3C, and the _dos_creatnew routine uses 
system call INT OxSB. If the file already exists, _dos_creat erases its contents and leaves 
its attributes unchanged; however, the _dos_creatnew routine fails if the file already exists. 


If successful, both routines return 0. Otherwise, they return the DOS error code and set 
errno to one of the following values: 


Constant Meaning 

EACCES Access denied because the directory is full or, for_dos_creat 
only, the file exists and cannot be overwritten 

EEXIST File already exists (_dos_creatnew only) 

EMFILE Too many open file handles 


ENOENT Path or file not found 
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Compatibility O ANS! m DOS O os2 oO UNIX O XENIX 


Example 


/* DCREAT.C: This program creates a file using the _dos_creat function. The 
* program cannot create a new file using the _dos_creatnew function 

* because it already exists. 

*/ 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <dos.h> 


void main() 

{ 
int fhl, fhe; 
int result; 


if( _dos_creat( "data", _A NORMAL, &fhl ) !=@ ) 
printf( "Couldn't create data file\n" ); 

else 

{ 


printf( "Created data file.\n" ); 


/* If _dos_creat is successful, the _dos_creatnew call 
* will fail since the file exists 
*/ 
if( _dos_creatnew( "data", _A_RDONLY, &fh2 ) !=@ ) 
printf( "Couldn't create data file\n" ); 
else 
{ 
printf( "Created data file.\n" ); 
_dos_close( fh2 ); 
} 
_dos_close( fhl ); 


Output 


Created data file. 
Couldn't create data file 
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Description Find the file with the specified attributes or find the next file with the specified attributes. 
#include <dos.h> 
#include <errno.h> 
unsigned _dos_findfirst( char “filename, unsigned attrib, struct find_t *fileinfo ); 
unsigned dos _findnext( struct find_t *fileinfo ); 
filename Target file name 
attrib Target attributes 
fileinfo File-information buffer 
Remarks The _dos_findfirst routine uses system call INT 0x4E to return information about the first 


instance of a file whose name and attributes match filename and attrib. 


The filename argument may use wildcards (* and ?). The attrib argument can be any of the 
following manifest constants: 


Constant Meaning 

_A_ARCH Archive. Set whenever the file is changed, and cleared by the 
DOS BACKUP command. 

_A_HIDDEN Hidden file. Cannot be found with the DOS DIR command. 


Returns information about normal files as well as about files 
with this attribute. 


_A NORMAL Normal. File can be read or written without restriction. 


_A_RDONLY Read-only. File cannot be opened for writing, and a file with 
the same name cannot be created. Returns information about 
normal files as well as about files with this attribute. 


_A_ SUBDIR Subdirectory. Returns information about normal files as well 
‘as about files with this attribute. 


_A SYSTEM System file. Cannot be found with the DOS DIR command. 
. Returns information about normal files as well as about files 
with this attribute. 


_A_VOLID Volume ID. Only one file can have this attribute, and it must 
be in the root directory. 
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Multiple constants can be combined (with the OR operator), using the vertical-bar (I ) 
character. 


If the attributes argument to either of these functions is_A RDONLY, A HIDDEN, 

_A_ SYSTEM, or _A_ SUBDIR, the function also returns any normal attribute files that 
match the filename argument. That is, a normal file does not have a read-only, hidden, sys- 
tem, or directory attribute. 


Information is returned in a find_t structure, defined in DOS.H. The find_t structure con- 
tains the following elements: 


Element Description 
char reserved[21] Reserved for use by DOS 
char attrib Attribute byte for matched path 
unsigned wr_time Time of last write to file 
‘unsigned wr_date Date of last write to file 
long size Length of file in bytes 
char name[13] ees name of matched file/directory, without 
the pat 


The formats for the wr_time and wr_date elements are in DOS format and are not usable 
by any other C run-time function. The time format is shown below: 


Bits Contents 

0-4 Number of 2-second increments (O—29) 
5-10 Minutes (0-59) 

11-15 Hours (0-23) 


The date format is shown below: 


Bits Contents 

0-4 Day of month (1-31) 
5-8 Month (1-12) 

9-15 Year (relative to 1980) 


Do not alter the contents of the buffer between a call to_dos_findfirst and a subsequent 
call to the _dos_findnext function. Also, the buffer should not be altered between calls to 
_dos_findnext. 
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The _dos_findnext routine uses system call Ox4F to find the next name, if any, that 
matches the filename and attrib arguments specified in a prior call to_dos_findfirst. The 
fileinfo argument must point to a structure initialized by a previous call to _dos_findfirst. 
The contents of the structure will be altered as described above if a match is found. 


Return Value If successful, both functions return 0. Otherwise, they return the DOS error code and set 
errno to ENOENT, indicating that filename could not be matched. 


Compatibility ©. O ANS| @™ovbOS QO OS2 QO UNIX CO XENIX 


Example 


/* DFIND.C: This program finds and prints all files in the current directory with 
* the .c extension. 
ais 


d#tinclude <stdio.h> 
d#Finclude <dos.h> 


main() 
{ 
struct find_t c_file; 


/* find first .c file in current directory */ 
dos_findfirst( "“*.c" A_NORMAL, &c_file ); 


printf( "Listing of .c files\n\n" ); 
printf( "File: %s is 41d bytes\n", c_file.name, c_file.size ); 


/* find the rest of the .c files */ 
while( _dos_findnext( &c_file ) == @ ) 
printf( "File: %s is %1d bytes\n", c_file.name, c_file.size ); 


Output 
Listing of .c files 


File: CHDIR.C is 524 bytes 
File: SIGFP.C is 2674 bytes 
File: MAX.C is 258 bytes 
File: CGETS.C is 577 bytes 
File: FWRITE.C is 1123 bytes 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Releases a block of memory (INT 0x49). 


#include <dos.h> 


#include <errno.h> 
unsigned _dos_freemem( unsigned seg ); 
seg Block to be released 


The _dos_freemem function uses system call 0x49 to release a block of memory pre- 
viously allocated by _dos_allocmem. The seg argument is a value returned by a previous 
call to_dos_allocmem. The freed memory may no longer be used by the application 
program. , 


If successful, _dos_freemem returns 0. Otherwise, it returns the DOS error code and sets 
errno to ENOMEM, indicating a bad segment value (one that does not correspond to a seg- 
ment returned by a previous _dos_allocmem call) or invalid arena headers. 


O ANS! @ DOS OF OS/ O UNIX OF XENIX 


_dos_allocmem, _dos_setblock, free functions 


/* DALOCMEM.C: This program allocates 2@ paragraphs of memory, increases 
* the allocation to 4@ paragraphs, and then frees the memory space. 


Ff 


#Hinclude <dos.h> 
dHinclude <stdio.h> 


void main() 


( 


unsigned segment; 
unsigned maxsize; 


/* Allocate 20 paragraphs */ 
if( _dos_allocmem( 28, &segment ) !=@ ) 
printf( "allocation failed\n" ); 


else 


printf( "allocation successful\n" ); 
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/* Increase allocation to 4@ paragraphs */ 

if( _dos_setblock( 48, segment, &maxsize ) !=@ ) 
printf( “allocation increase failed\n" ); 

else 
printf( “allocation increase successful\n" ); 


/* Free memory */ 
if( _dos_freemem( segment ) != @ ) 
printf( “free memory failed\n" ); 
else 
printf( “free memory successful\n" ); 


Output 


allocation successful 
allocation increase successful 
free memory successful 
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Description Gets current system date using system call INT 0x2A. 
#include <dos.h> | 
void _dos_getdate( struct dosdate_t *date ); 
date Current system date 
Remarks The _dos_getdate routine uses system call 0x2A to eben the current system date. The 


date is returned in a dosdate_t structure, defined in DOS.H. 


The dosdate_t structure contains the following elements: 


Element Description 

unsigned char day 1-31 

unsigned char month 1-12 

unsigned int year 1980—2099 

unsigned char dayofweek 0-6 (0 = Sunday) 
Return Value None. . 


Compatibility O ANS! @ DOS OF OS/? CO UNIX OO XENIX 


See Also _dos_gettime, _dos_setdate, _dos_settime, gmtime, localtime, mktime, _strdate, 
_Strtime, time 

Example 

/* DGTIME.C: This program gets and displays current date and time values. */ 


#Hinclude <stdio.h> 
#Hinclude <dos.h> 


void main() 


struct dosdate_t date; 
struct dostime_t time; 
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/* Get current date and time values */ 


_dos_getdate( &date ); 
dos_gettime( &time ); 


printf( "Today's date is %d-%d-%d\n", date.month, date.day, date.year ); 
printf( “The time is 402d:%@2d\n", time.hour, time.minute ); 


Output 


Today's date is 6-15-1989 
The time is 18:97 


_dos_getdiskfree | 202 


Description 


Remarks — 


Return Value 


Compatibility 


See Also 


Example 


Gets disk information using system call INT 0x36. 


#include <dos.h> 


#include <errno.h> 
unsigned _dos_getdiskfree( unsigned drive, struct diskfree_t “diskspace ); 


drive Drive number (default is 0) 


diskspace Buffer to hold disk information 


The _dos_getdiskfree routine uses system call 0x36 to obtain information on the disk 
drive specified by drive. The default drive is 0, drive A is 1, drive B is 2, and so on. 
Information is returned in the diskfree_t structure (defined in DOS.H) pointed to by 
diskspace. . 


The struct diskfree_t structure contains the following elements: 


Element Description 

unsigned total_clusters Total clusters on disk 
unsigned avail_clusters ___ Available clusters on disk 
unsigned sectors_per_cluster Sectors per cluster 
unsigned bytes_per_sector Bytes per sector 


If successful, the function returns 0. Otherwise, it returns a nonzero value and sets errno to 
EINVAL, indicating that an invalid drive was specified. 
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_dos_getdrive, dos_setdrive 


/* DGDISKFR.C: This program displays information about the default disk drive. */ 


d#Hinclude <stdio.h> 
#Hinclude <dos.h> 
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main() 


{ 


struct diskfree_t drive; 


/* Get information on default disk drive @ */ 


_dos_getdiskfree( @, &drive ); 


printf( “total clusters: %4d\n", drive.total_clusters ); 

printf( “available clusters: %d\n", drive.avail_clusters ); 
printf( “sectors per cluster: %d\n", drive.sectors_per_cluster ); 
printf( “bytes per sector: %d\n", drive.bytes_per_sector ); 


Output 


total clusters: 9913 
available clusters: 6030 
sectors per cluster: 4 
bytes per sector: 512 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets the current disk drive using system call INT 0x19. 


~ #include <dos.h> 


void dos_getdrive( unsigned “drive ); 
drive Current-drive return buffer 


The _dos_getdrive routine uses system call 0x19 to obtain the current disk drive. The cur- 
rent drive is returned in the word that drive points to: 1 = drive A, 2 = drive B, and so on. 


None. 
O ANS! @ DOS OFoS72 OG UNIX O XENIX 


_dos_getdiskfree, dos setdrive, _getdrive 


/* DGDRIVE.C: This program prints the letter of the current drive, 
* changes the default drive to A, then returns the number of disk drives. 


wy 


#Hinclude <stdio.h> 
#Hinclude <dos.h> 


void main() 


{ 


unsigned olddrive, newdrive; 
unsigned number_of_drives; 


/* Print current default drive information */ 
_dos_getdrive( &olddrive ); 
printf( "The current drive is: %c\n", 'A' + olddrive - 1 ); 


/* Set default drive to be drive A */ 
printf( "Changing default drive to A\n"); 
_dos_setdrive( 1, &number_of_drives ); 


/* Get new default drive information and total number of drives */ 
_dos_getdrive( &newdrive ); 

printf( "The current drive is: %c\n", 'A' + newdrive - 1 ); 
printf( "Number of logical drives: %d\n", number_of_drives ); 
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/* Restore default drive */ 
_dos_setdrive( olddrive, &number_of_drives ); 


Output 


The current drive is: C 
Changing default drive to A 
The current drive is: A 
Number of logical drives: 26 
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Description 


Remarks 


Return Value 


Gets the current attributes of a file or directory, using system call INT 0x43. 


#include <dos.h> 


#include <errno.h> 
unsigned dos _getfileattr( char *pathname, unsigned “attrib ); 


pathname Full path of target file/directory 


attrib Word to store attributes in 


The _dos_getfileattr routine uses system call 0x43 to obtain the current attributes of the 
file or directory pointed to by pathname . The attributes are copied to the low-order byte of 
the attrib word. Attributes are represented by manifest constants, as described below: 


Constant Meaning 

_A ARCH Archive. Set whenever the file is changed, or cleared by the 
; DOS BACKUP command. 

_A_HIDDEN Hidden file. Cannot be found by a directory search. 

_A NORMAL Normal. File can be read or written without restriction. 

_A_RDONLY Read-only. File cannot be opened for a write, and a file with 

the same name cannot be created. 

_A_ SUBDIR Subdirectory. 

any STEM. System file. Cannot be found by a directory search. 

_A _VOLID Volume ID. Only one file can have this attribute, and it must 


be in the root directory. 


If successful, the function returns 0. Otherwise, it returns the DOS error code and sets 
errno to ENOENT, indicating that the target file or directory could be found. 
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Compatibility O ANS! ® DoS oO os2 oO UNKX O XENI 
See Also access, chmod, dos_setfileattr, umask 
Example ___ 


/* DGFILEAT.C: This program creates a file with the specified attributes, 
* then prints this information before changing the file attributes back 
* to normal. 

*/ 


include <stdio.h> 
dFinclude <dos.h> 


void main() 

{ 
unsigned oldattrib, newattrib; 
int fh; 


/* Get and display file attribute */ 
_dos_getfileattr( “DGFILEAT.C", &oldattrib ); 
printf( “Attribute: @x%.4x\n", oldattrib ); 
if( ( oldattrib & _A_RDONLY ) !=@ ) 

printf( "Read only file\n" ); 
else 

printf( "Not a read only file.\n" ); 


/* Reset file attribute to normal file */ 
_dos_setfileattr( "DGFILEAT.C", _A RDONLY ); 


_dos_getfileattr( “DGFILEAT.C", &newattrib ); 
printf( “Attribute: 0x%.4x\n", newattrib ); 


/* Restore file attribute */ 
_dos_setfileattr( "DGFILEAT.C", oldattrib ); 
_dos_getfileattr( “DGFILEAT.C", &newattrib ); 
printf( "Attribute: @x%.4x\n", newattrib ); 


Output 


Attribute: @x@820 
Not a read only file. 
Attribute: @x@@@1 
Attribute: @x@020 
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Description 


Remarks 


Return Value 


Gets the date and time a file was last written, using system call INT 0x57. 


#include <dos.h> 


#include <errno.h> 


unsigned dos _getftime( int handle, unsigned *date, unsigned *time ); 


handle Target file 
- date Date-return buffer 
time Time-return buffer 


_ The _dos_getftime routine uses system call 0x57 to get the date and time that the specified 


file was last written. The file must have been opened with a call to _dos_open or 
_dos_creat prior to calling _dos_getftime. The date and time are returned in the words 
pointed to by date and time. The values appear in the DOS date and time format: 


Time Bits Meaning 

0-4 Number of 2-second increments (0-29) 
5-10 Minutes (0-59) 

11-15 Hours (0-23) 

Date Bits Meaning 

0-4 Day (1-31) 

5-8 Month (1-12) 

9-15 Year (1980-2099) 


If successful, the function returns 0. Otherwise, it returns the DOS error code and sets 
errno to EBADF, indicating that an invalid file handle was passed. 
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Compatibility O ANS! @ OOS O08 OS7 O UNIX O XENIX 


See Also _dos_setftime, fstat, stat 


Example 


/* DGFTIME.C: This program displays and modifies the date and time 
* fields of a file. j 
* / \ 


fHinclude <fcntl.h> 
fHinclude <stdio.h> 
dHinclude <stdlib.h> 
#Hinclude <dos.h> 


void main() 
{ 

/* FEDC BA98 7654 3210 */ 
unsigned new_date = Ox184f; /* Q@01 1900 @10@ 1111 2/15/92 */ 
unsigned new_time = @x48e@; /* 01800 1900 1110 @@@0 9:07 AM */ 
unsigned old_date, old_time; 


int fh; 


/* Open file with _dos_open function */ 
if( _dos_open( “dgftime.obj", O_RDONLY, &fh ) !=@ ) 
exit( 1 ); 


/* Get file date and time */ 

_dos_getftime( fh, &0ld_date, &old_time ); 
printf( "Old date field: @x%.4x\n", old_date ); 
printf( “Old time field: @x%.4x\n", old_time ); 
system( “dir dgftime.obj" ); 


/* Modify file date and time */ 

if( !_dos_setftime( fh, new_date, new_time ) ) 

( 
_dos_getftime( fh, &new_date, &new_time ); 
printf( "New date field: @x%.4x\n", new_date 
printf( "New time field: @x%.4x\n", new_time 
system( “dir dgftime.obj" ); 


~~ ww 
we we 


/* Restore date and time */ 

_dos_setftime( fh, old_date, old_time ); 
} ; 
_dos_close( fh ); 
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210 


Output 


Old date field: @xl2cf 
Old time field: @x94bb 


Volume in drive C is 0S2 
Directory of C:\LIBREF 


DGFTIME OBJ 3923 6-15-89 6:37p 
1 File(s) 13676544 bytes free 


New date field: @x184f 
New time field: 9x48e@ 


Volume in drive C is 0S2 
Directory of C:\LIBREF 


DGFTIME OBJ 3923. “2215=92°. 9: 07a 
1 File(s) 13676544 bytes free 
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Description Gets the current system time, using system call INT 0x2C, 

#include <dos.h> | 

void dos_gettime( struct dostime_t *time ); 

time Current system time 
Remarks The _dos_gettime routine uses system call Ox2C to obtain the current system time. The 


Return Value 
Compatibility 
See Also 


Example 


time is returned in a dostime_t structure, defined in DOS.H. 


The dostime_t structure contains the following elements: 


Element 


unsigned char hour 
unsigned char minute 
unsigned char second 


unsigned char hsecond 
None. 


C)} ANS! M@ DOS O OS/2 


Description 

0-23 

0-59 

0-59 

1/100 second; 0-99 


O UNIX O XENIX 


s 


_dos_getdate, dos_setdate, _dos_settime, gmtime, localtime, _strtime 


/* DGTIME.C: This program gets and displays current date and time values. */ 


#Hinclude <stdio.h> 
d#Hinclude <dos.h> 


void main() 
{ 


struct dosdate_t date; 
struct dostime_t time; 
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/* Get current date and time values */ 


_dos_getdate( &date ); 
_dos_gettime( &time ); 


printf( “Today's date is %4d-%d-%d\n", date.month, date.day, date.year ); 
printf( "The time is %202d:%02d\n", time.hour, time.minute ); 


Output 


Today's date is 6-15-1989 
The time is. 18:07 
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_dos_getvect 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Gets the current value of the interrupt vector, using ate call INT 0x35. 
#include <dos.h> 

void (_interrupt far * dos_getvect( unsigned intnum))(); 

intnum Target interrupt vector 


The _dos_getvect routine uses system call INT 0x35 to get the current value of the inter- 
rupt vector specified by intnum. 


This routine is typically used in conjunction with the _dos_setvect function. To replace an 
interrupt vector, first save the current vector of the interrupt using dos_getvect. Then set 
the vector to your own interrupt routine with dos_setvect. The saved vector can later be 
restored, if necessary, using _dos_setvect. The user-defined routine may also need the orig- 
inal vector in order to call that vector or chain to it with _chain_intr. 


The function returns a far pointer for the intnum interrupt to the current handler, if there 
is one. 
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_chain_intr, _dos_ keep, _dos_setvect 
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Description Installs TSR (terminate-and-stay-resident) programs in memory, using system call 
INT 0x31. 


#include <dos.h> 


void dos keep( unsigned retcode, unsigned memsize ); 


retcode Exit status code 
memsize Allocated resident memory (in 16-byte paragraphs) 
Remarks The _dos_keep routine installs TSRs (terminate-and-stay-resident programs) in memory, 


using system call INT 0x31. 


The routine first exits the calling process, leaving it in memory. It then returns the low- 
order byte of retcode to the parent of the calling process. Before returning execution to 
the parent process, _dos_keep sets the allocated memory for the now-resident process to 
memsize 16-byte paragraphs. Any excess memory is returned to the system. 


The _dos_ keep function calls the same internal routines called by exit. It therefore takes 
the following actions: 


a Calls atexit and onexit if defined. 
m@ Flushes all file buffers. 


m™ Restores interrupt vectors replaced by the C start-up code. The primary one is interrupt 
0 (divide by zero). If the emulator math library is used and there is no coprocessor, 
interrupts 0x34 through Ox3D are restored. If there is a coprocessor, interrupt 2 is 
restored. 


The _dos_keep function does not automatically close files; you should do this specifically 
unless you want files opened by the TSR installation code to remain open for the TSR. 


Do not use the emulator math library in TSRs unless you are familiar with the C start-up 
code and the coprocessor. Use the alternate math package (not supplied with Microsoft 
QuickC) if the TSR must do floating-point math. 


Do not run programs that use _dos_keep from inside the Microsoft Programmer’s 
WorkBench environment, since doing so causes subsequent memory problems. The 
_dos_keep function terminates the program when executed in the Programmer’s 
WorkBench environment. 


Return Value None. 
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Compatibility O ANS! @ DOS O OS/72 O UNIX O XENIX 


See Also _cexit, _chain_intr, dos getvect, dos _setvect, exit 
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Description Opens a file, using system call INT 0x3D. 


#include <dos.h> 
#include <errno.h> 
#include <fentl.h> Access mode constants 


#include <share.h> Sharing mode constants 


unsigned _dos_open( char *filename, unsigned mode, int *handle ); 


filename Path to an existing file 
mode Permissions 
handle Pointer to integer 
Remarks The _dos_open routine uses system call INT 0x3D to open the existing file pointed to by 


filename. The handle for the opened file is copied into the integer pointed to by handle. 
The mode argument specifies the file’s access, sharing, and inheritance modes by combin- 
ing (with the OR operator) manifest constants from the three groups shown below. At 
most, one access mode and one sharing mode can be specified at a time. 


Constant Mode Meaning 
O_RDONLY Access Read-only 
O_WRONLY Access Write-only 
O_RDWR Access Both read and write 
SH_COMPAT Sharing Compatibility 
SH_DENYRW Sharing Deny reading and writing 
SH_DENYWR Sharing Deny writing 
SH_DENYRD | Sharing Deny reading 
SH_DENYNO _ Sharing Deny neither 
O_NOINHERIT Inheritance by the child File is not inherited 
process 


Do not use the DOS interface I/O routines in conjunction with the console, low-level, or 
stream I/O routines. 
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Return Value If successful, the function returns 0. Otherwise, it returns the DOS error code and sets 
errno to one of the following manifest constants: 


Constant Meaning 


EACCES Access denied (possible reasons include specifying a directory 
or volume ID for filename, or opening a read-only file for 
write access) 


EINVAL Sharing mode specified when file sharing not installed, or 
access-mode value is invalid 

EMFILE Too many open file handles 

ENOENT Path or file not found 


Compatibility O ANS| @ DOS QO os72 O UNIX O XENI 


See Also _dos_ close, _dos read, _dos_ write 


Example 


/* DOPEN.C: This program uses DOS 1/0 functions to open and close a file. */ 


d#Finclude <fcntl.h> 
dHinclude <stdio.h> 
#Hinclude <dos.h> 


void main() 


{ 
int fh; 


/* Open file with _dos_open function */ 
if( _dos_open( “datal", O_RDONLY, &fh ) !=@ ) 
perror( "Open failed on input file\n" ); 
else 
printf( "Open succeeded on input file\n" ); 


/* Close file with _dos_close function */ 
if( _dos_close( fh ) !=9@ ) 

perror( "Close failed\n" ); 
else 

printf( "File successfully closed\n" ); 
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Output 


Open succeeded on input file 
File successfully closed 
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_dos_read 


Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Reads data from a file, using system call INT 0x3F. 
#include <dos.h> 


unsigned _dos_read( int handle, void _far *buffer, unsigned count, 
unsigned *numread ); 


handle File to read 

buffer Buffer to write to 

count Number of bytes to read 
numread : Number of bytes actually read 


The _dos_read routine uses system call INT Ox3F to read count bytes of data from the file 
specified by handle. The routine then copies the data to the buffer pointed to by buffer. 
The integer pointed to by numread will show the number of bytes actually read, which 
may be less than the number requested in count. If the number of bytes actually read is 0, it 
means the routine tried to read at end-of-file. 


Do not use the DOS interface I/O routines in conjunction with the console, low-level, or 
stream I/O routines. 


If successful, the function returns 0. Otherwise, it returns the DOS error code and sets 
errno to one of the following constants: 


Constant Meaning 
EACCES Access.denied (handle is not open for read access) 
EBADF File handle is invalid 


O ANS| @ DOS 0 OS/2 OF UNIX OO XENIX 


_dos close, _dos_open, _dos_ write, read 


/* DREAD.C: This program uses the DOS I/0 operations to read the contents 


* of a file. 


ot 
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fHinclude <fcntl.h> 
#include <stdlib.h> 
#Hinclude <stdio.h> 
#Hinclude <dos.h> 


void main() 

{ 
int fh; 
char buffer[5@]; 
unsigned number_read; 


/* Qpen file with _dos_open function */ 

if( _dos_open( "dread.c", O_RDONLY, &fh ) !=@ ) 
perror( "Open failed on input file\n" ); 

else 
printf( "Open succeeded on input file\n" ); 


/* Read data with _dos_read function */ 
_dos_read( fh, buffer, 50, &number_read ); 
printf( "First 48 characters are: %.4@s\n\n", buffer ); 


/* Close file with _dos_close function */ 
_dos_close( fh ); 

} 

Output 


Open succeeded on input file 
First 40 characters are: /* DREAD.C: This program uses the DOS I/ 
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_dos_sethlock 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Changes the size of a memory segment, using system call INT Ox4A. 
#include <dos.h> 


unsigned _dos_setblock( unsigned size, unsigned seg, unsigned *maxsize ); 


size New segment size 
seg Target segment 
maxsize Maximum-size buffer 


The _dos_setblock routine uses system call INT 0x4A to change the size of seg, pre- 
viously allocated by _dos_allocmem, to size paragraphs. If the request cannot be satisfied, 
the maximum possible segment size is copied to the buffer pointed to by maxsize. 


The function returns 0 if successful. If the call fails, it returns the DOS error code and 

sets errno to ENOMEM, indicating a bad segment value was passed. A bad segment value 
is one that does not correspond to a segment returned from a previous _dos_allocmem 
call, or one that contains invalid arena headers. 


O ANS! @ DOS OF oS2 QO UNIX O XENIX 


_dos_allocmem, _dos freemem, realloc functions 


/* DALOCMEM.C: This program allocates 28 paragraphs of memory, increases 
* the allocation to 40 paragraphs, and then frees the memory space. 


af 


#Hinclude <dos.h> 
dFinclude <stdio.h> 


void main() 


{ 


unsigned segment; 
unsigned maxsize; 
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/* Allocate 28 paragraphs */ 

if( _dos_allocmem( 28, &segment ) !=@ ) 
printf( “allocation failed\n" ); 

else 
printf( “allocation successful\n" ); 


/* Increase allocation to 4@ paragraphs */ 

if( _dos_setblock( 40, segment, &maxsize ) !=@ ) 
printf( “allocation increase failed\n" |); 

else 
printf( "allocation increase successful\n" ); 


/* Free memory */ 
if( _dos_freemem( segment ) != @ ) 
printf( "free memory failed\n" ); 
else 
printf( "free memory successful\n" ); 


Output 


allocation successful 
allocation increase successful 
free memory successful 
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_dos_setdate 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Sets the current system date, using system call INT 0x2B. 
#include <dos.h> 

unsigned dos _setdate( struct dosdate_t *date ); 

date New system date 


The _dos_setdate routine uses system call INT 0x2B to set the current system date. The 
date is stored in the dosdate_t structure pointed to by date, defined in DOS.H. The 
dosdate_t structure contains the following elements: 


Element Description 
unsigned char day 1-31 

unsigned char month 1-12 

unsigned int year 1980-2099 
unsigned char dayofweek 0-6 (0 = Sunday) 


If successful, the function returns 0. Otherwise, it returns a nonzero value and sets errno to 
EINVAL, indicating an invalid date was specified. 


O ANS! m DOS © oS2 O UNIX O XENIX 


_dos_gettime, _dos_setdate, _dos_settime, gmtime, localtime, mktime, _strdate, 
_strtime, time 


/* DSTIME.C: This program changes the time and date values and displays the 
* new date and time values. 


Fj 


#Hinclude <dos.h> 

#tinclude <conio.h> 
#Hinclude <stdio.h> 
#Hinclude <time.h> 
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void main() 
( 
{7}, { 1984 } }; 


struct dosdate_t olddate, newdate }, 
}, ( 45 3}, € 30), (8) }; 


struct dostime_t oldtime, newtime 
char datebuf(40], timebuf[4@]; 


{ (4 
{ { 3 


/* Get current date and time values */ 
_dos_getdate( &olddate ); 
_dos_gettime( &oldtime ); 

printf( "4s s\n" , _strdate( datebuf ), _strtime( timebuf ) ); 
/* Modify date and time structures */ 

_dos_setdate( &newdate ); 

_dos_settime( &newtime ); 

printf( "%s s\n" , _Sstrdate( datebuf ), _strtime( timebuf ) ); 


/* Restore old date and time */ 


_dos_setdate( &olddate ); 
_dos_settime( &oldtime ); 


Output 


86/15/89 18:26:09 
07/04/84 83:45:30 
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_dos_setdrive 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Sets the default drive, using system call INT Ox0E. 
#include <dos.h> 
void dos_setdrive( unsigned drive, unsigned *numdrives ); 


drive New default drive 


numdrives Total drives available 


The _dos_setdrive routine uses system call INT Ox0E to set the current default drive to the 
drive argument: 1 = drive A, 2 = drive B, and so on. The numdrives argument indicates the 
total number of drives in the system. If this value is 4, for example, it does not mean the 
drives are designated A, B, C, and D; it means only that four drives are in the system. 


There is no return value. If an invalid drive number is passed, the function fails without in- 
dication. Use the _dos_getdrive routine to verify whether the desired drive has been set. 


O ANS! DOS OF OS/72 O UNIX OF XENIX 


_dos_getdiskfree, _dos_getdrive 
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/* DGDRIVE.C: This program prints the letter of the current drive, 
* changes the default drive to A, then returns the number of disk drives. 


bad 


dFinclude <stdio.h> 
dFinclude <dos.h> 


void main() 


unsigned olddrive, newdrive; 
unsigned number_of_drives; 


/* Print current default drive information */ 
_dos_getdrive( &olddrive ); 
printf( "The current drive is: %c\n", ‘A’ + olddrive - 1 ); 


/* Set default drive to be drive A */ 
printf( “Changing default drive to A\n"); 
_dos_setdrive( 1, &number_of_drives ); 
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/* Get new default drive information and total number of drives */ 
_dos_getdrive( &newdrive ); 

printf( "The current drive is: %c\n", ‘A' + newdrive - 1 ); 
printf( "Number of logical drives: %d\n", number_of_drives ); 


/* Restore default drive */ 
_dos_setdrive( olddrive, &number_of_drives ); 


Output 


The current drive is: C 
Changing default drive to A 
The current drive is: A 
Number of logical drives: 26 
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Description Sets the attributes of the file or directory, using system call INT 0x43. 
#include <dos.h> 


unsigned _dos setfileattr( char *pathname, unsigned attrib ); 


pathname Full path of target file/directory 
attrib New attributes 
Remarks The _dos_setfileattr routine uses system call INT 0x43 to set the attributes of the file or 


directory pointed to by pathname. The actual attributes are contained in the low-order byte 
of the attrib word. Attributes are represented by manifest constants, as described below: 


Constant Meaning 

_A ARCH Archive. Set whenever the file is changed, or cleared by the 
DOS BACKUP command. 

_A HIDDEN Hidden file. Cannot be found by a directory search. 

_A_NORMAL Normal. File can be read or written to without restriction. 

_A RDONLY Read-only. File cannot be opened for writing, and a file with 
the same name cannot be created. 

_A_SUBDIR Subdirectory. 

_A SYSTEM System file. Cannot be found by a directory search. 

_A _VOLID Volume ID. Only one file can have this attribute, and it must 


be in the root directory. 


Return Value The function returns 0 if successful. Otherwise, it returns the DOS error code and sets 
errno to one of the following: 


Constant Meaning 
EACCES | Access denied; cannot change the volume ID or the 
subdirectory. 


ENOENT No file or directory matching the target was found. 
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Compatibility O ANSI! @ DOS OF 0S/?2 O UNIX O XENIX 


See Also _dos_getfileattr 


Example 


/* DGFILEAT.C: This program creates a file with the specified attributes, 
* then prints this information before changing the file attributes back 
* to normal. 
ia: 


#include <stdio.h> 
#Hinclude <dos.h> 


void main() 

{ 
unsigned oldattrib, newattrib; 
Minow aie 


/* Get and display file attribute */ 
_dos_getfileattr( "DGFILEAT.C", &oldattrib ); 
printf( “Attribute: 0x%.4x\n", oldattrib ); 
if( ( oldattrib & _A_RDONLY ) !=9@ ) 

printf( "Read only file\n" ); 
else 

printf( "Not a read only file.\n" ); 


/* Reset file attribute to normal file */ 
_dos_setfileattr( "“DGFILEAT.C", _A_RDONLY ); 


_dos_getfileattr( "DGFILEAT.C", &newattrib ); 
printf( “Attribute: @x%.4x\n", newattrib ); 


/* Restore file attribute */ 
_dos_setfileattr( "DGFILEAT.C", oldattrib ); 
_dos_getfileattr( "DGFILEAT.C", &newattrib ); 
printf( "Attribute: @x%.4x\n", newattrib ); 


Output 


Attribute: @x@020 
Not a read only file. 
Attribute: %x@Q@1 
Attribute: @x@820 
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Description Sets the date and time for a file, using system call INT 0x57. 

#include <dos.h> 

unsigned dos _setftime( int handle, unsigned date, unsigned time ); 

handle Target file 

date Date of last write 

time Time of last write 
Remarks The _dos_setftime routine uses system call INT 0x57 to set the date and time at which the 


Return Value 


file identified by handle was last written to. These values appear in the DOS date and time 
format, described in the following lists: 


Time Bits Meaning 

0-4 | Number of two-second increments (0-29) 

5-10 Minutes (0-59) 

11-15 ~ Hours (0-23) 

Date Bits Meaning 

0-4 Day (1-31) 

5-8 Month (1-12) 

9-15 Year since 1980 (for example, 1989 is stored as 9) 


If successful, the function returns 0. Otherwise, it returns the DOS error code and sets 
errno to EBADF, indicating that an invalid file handle was passed. 
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Compatibility O ANS! @ DOS OF OS/f O UNIX O XENIX 
See Also _dos_getftime, fstat, stat 
Example 


/* DGFTIME.C: This program displays and modifies the date and time 
* fields of a file. 
a 


#include <fcnt1.h> 
#Finclude <stdio.h> 
dHinclude <stdlib.h> 
#Hinclude <dos.h> 


void main() 
{ 

/* FEDC BA98 7654 3210 */ 
unsigned new_date = QOx184f; /* 0001 1000 0108 1111 2/15/92 */ 
unsigned new_time = @x48e@; /* 8100 1080 1110 @Q@B@ 9:07 AM */ 
unsigned old_date, old_time; 


int fh; 


/* Open file with _dos_open function */ 
if( _dos_open( “dgftime.obj", O_RDONLY, &fh ) !=@ ) 
extic a} 


/* Get file date and time */ 

_dos_getftime( fh, &old_date, &old_time ); 
printf( "Old date field: @x%.4x\n", old_date ); 
printf( "Old time field: @x%.4x\n", old_time ); 
system( "dir dgftime.obj" ); 


/* Modify file date and time */ 
if( !_dos_setftime( fh, new_date, new_time ) ) 
{ 

_ _dos_getftime( fh, &new_date, &new_time ); 
printf( "New date field: @x%.4x\n", new_date ); 
printf( "New time field: @x%.4x\n", new_time ); 
system( "dir dgftime.obj" ); 


/* Restore date and time */ 
_dos_setftime( fh, old_date, old_time ); 
} 
_dos_close( fh ); 
} 
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Output 


Old date field: @xl2cf 
Old time field: @x94bb 


Volume in drive C is 082 
Directory of C:\LIBREF 


DGFTIME OBJ 3923 6-15-89 6:37p 
1 File(s) 13676544 bytes free 


New date field: @x184f 
New time field: @x48e@ 


Volume in drive C is 0S2 
Directory of C:\LIBREF 


DGFTIME OBJ 3923 2-15-92 9:@7a 
1 File(s) 13676544 bytes free 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Sets the current system time, using system call INT 0x2D. 
#include <dos.h> 

unsigned _dos_settime( iia dostime_t “time ); 

time New system time 


The _dos_settime routine uses system call INT 0x2D to set the current system time to the 
value stored in the dostime_t structure that time points to, as defined in DOS.H. The 
dostime_t structure contains the following elements: 


Element Description 

unsigned char hour 0-23 

unsigned char minute 0-59 

unsigned char second 0-59 

unsigned char hsecond Hundredths of a second; 0-99 


If successful, the function returns 0. Otherwise, it returns a nonzero value and sets errno to 
EINVAL, indicating an invalid time was specified. 
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_dos_getdate, _dos_gettime, _dos_setdate, gmtime, localtime, mktime, 
_Strdate, _strtime 


/* DSTIME.C: This program changes the time and date values and displays the 
* new date and time values. 


aa 


#Finclude <dos.h> 

d#Hinclude <conio.h> 
dHinclude <stdio.h> 
fHinclude <time.h> 
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void main() 

{ 
struct dosdate_t olddate, newdate = { { 
struct dostime_t oldtime, newtime = { { 
char datebuf[40], timebuf(40); 


}, ( 1984 } }; 
Sake oO ks. Lee: os 


>n~ 


/* Get current date and time values */ 

_dos_getdate( &olddate ); 

_dos_gettime( &oldtime ); 

printf( “%s s\n" , _strdate( datebuf ), _strtime( timebuf ) ); 


/* Modify date and time structures */ 
_dos_setdate( &newdate ); 
_dos_settime( &newtime ); 
printf( “%s s\n" , _strdate( datebuf ), _strtime( timebuf ) ); 
/* Restore old date and time */ 
_dos_setdate( &olddate ); 
_dos_settime( &oldtime ); 
} 


Output 


Q6/15/89 18:26:89 
87/04/84 03:45:30. 
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Description 


Remarks 


Sets the current value of the interrupt vector, using system call INT 0x25. 


| #include <dos.h> 


void dos_setvect( unsigned intnum, void( interrupt far *handler)()); 


intnum Target-interrupt vector 


handler Interrupt handler for which to assign intnum 


The _dos_setvect routine uses system call INT 0x25 to set the current value of the inter- 
rupt vector intnum to the function pointed to by handler. Subsequently, whenever the 
intnum interrupt is generated, the handler routine will be called. If handler is a C function, 
it must have been previously declared with the interrupt attribute. Otherwise, you must 
make sure that the function satisfies the requirements for an interrupt-handling routine. For 
example, if handler is an assembler function, it must be a far routine that returns with an 
IRET instead of a RET. 


The interrupt attribute indicates that the function is an interrupt handler. The compiler 
generates appropriate entry and exit sequences for the interrupt-handling function, includ- 
ing saving and restoring all registers and executing an IRET instruction to return. 


The _dos_setvect routine is generally used with the _dos _getvect function. To replace an 
interrupt vector, first save the current vector of the interrupt using _dos_getvect. Then set 
the vector to your own interrupt routine with dos_setvect. The saved vector can later be 
restored, if necessary, using _dos_setvect. The user-defined routine may also need the orig- 


inal vector in order to call it or to chain to it with _chain_intr. 
& 


Registers and Interrupt Functions 


When you call an interrupt function, the DS register is initialized to the C data segment. 
This allows you to access global variables from within an interrupt function. 


In addition, all registers except SS are saved on the stack. You can access these registers 
within the function if you declare a function parameter list containing a formal parameter 
for each saved register. The following example illustrates such a declaration: 
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void _interrupt _far int_handler( unsigned _es, unsigned _ds, 
unsigned _di, unsigned _si, 
unsigned _bp, unsigned _sp, 
unsigned _bx, unsigned _dx, 
unsigned _cx, unsigned _ax, 
unsigned _ip, unsigned _cs, 
unsigned _flags ) 


} 
The formal parameters must appear in the opposite order from which they are pushed onto 
the stack. You can omit parameters from the end of the list in a declaration, but not from 


the beginning. For example, if your handler needs to use only DI and SI, you must still 
provide ES and DS, but not necessarily BX or DX. 


You can pass additional arguments if your interrupt handler will be called directly from C 
rather than by an INT instruction. To do this, you must declare all register parameters and 
then declare your parameter at the end of the list. 


The compiler always saves and restores registers in the same, fixed order. Thus, no matter 
what names you use in the formal parameter list, the first parameter in the list refers to ES, 
the second refers to DS, and so on. If your interrupt routines will use in-line assembler, 
you should distinguish the parameter names so that they will not be the same as the real 
register names. 


If you change any of the register parameters of an interrupt function while the function is 
executing, the corresponding register contains the changed value when the function re- 
turns. For example: 


void _interrupt _far int_handler( unsigned _es, unsigned _ds, 
unsigned _di, unsigned _si ) 


This code causes the DI register to contain —1 when the handler function returns. It is not a 
good idea to modify the values of the parameters representing the IP and CS registers in in- 
terrupt functions. If you must modify a particular flag (such as the carry flag for certain 
DOS and BIOS interrupt routines), use the OR operator (| ) so that other bits in the flag 
register are not changed. 


When an interrupt function is called by an INT instruction, the interrupt-enable flag is 
cleared. If your interrupt function needs to do significant processing, you should use the 
_enable function to set the interrupt flag so that interrupts can be handled. 
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Return Value 


Compatibility 


See Also 


Precautions for Interrupt Functions 


Since DOS is not reentrant (a DOS interrupt cannot be called from inside a DOS interrupt), 
it is usually not safe to call from inside an interrupt function any standard library function 
that calls DOS INT 21H. Similar precautions apply to many BIOS functions. Functions 
that rely on INT 21H calls include I/O functions and the _dos family of functions. Func- 
tions that rely on the machine’s BIOS include graphics functions and the _bios family of 
functions. It is usually safe to use functions that do not rely on INT 21H or BIOS, such as 
string-handling functions. Before using a standard library function in an interrupt function, 
be sure that you are familiar with the action of the library function. 


None. 
O ANS! @ DOS Oos2 QO UNIX O XENIX 


_chain_intr, _dos_getvect, _dos_keep 
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Description Writes a buffer to a file, using system call INT 0x40. 
#include <dos.h> 
unsigned dos _ write( int handle, void _far *buffer, unsigned count, 
unsigned *numwrt ); 
handle File to write to 
buffer Buffer to write from 
count Number of bytes to write 
numwrt Number of bytes actually written 
+ Remarks The _dos_write routine uses system call INT 0x40 to write data to the file that handle ref- 


Return Value 


Compatibility 


See Also 


Example 


erences; count bytes of data from the buffer to which buffer points are written to the file. 
The integer pointed to by numwrt will be the number of bytes actually written, which may 
be less than the number requested. 


Do not use the DOS interface routines with the console, low-level, or stream I/O routines. 


If successful, the function returns 0. Otherwise, it returns the DOS error code and sets 
errno to one of the following manifest constants: 


Constant . Meaning 

EACCES Access denied (handle references a file not open for write 
access) 

EBADF Invalid file handle 


O ANS| @ OOS OF 0S/7 O UNIX O XENIX 


_dos close, _dos_open, _dos_ read, write 


/* DWRITE.C: This program uses DOS I/0 functions to write to a file. */ 


#Finclude <fcntl.h> 
fHinclude <stdio.h> 
dHinclude <stdlib.h> 
#Hinclude <dos.h> 
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void main() 

{ 
char out_buffer[] = "Hello"; 
int fh; 
unsigned n_written; 


/* Open file with _dos_creat function */ 
if( _dos_creat( "data", _A_NORMAL, &fh ) == 9 ) 
{ 
/* Write data with _dos_write function */ 
_dos_write( fh, out_buffer, 5, &n_written ); 
printf( "Number of characters written: %4d\n", n_written ); 


_dos_close( fh ); 
printf( "Contents of file are:\n" ); 
system( "type data" ); 


Output 


Number of characters written: 5 
Contents of file are: 
Hello 
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dosexterr 


Description 


Remarks 


Return Value 


Compatibility 


Gets register values returned by INT 0x59. 

#include <dos.h> 

int dosexterr( struct DOSERROR “errorinfo ); 

errorinfo _ Extended DOS error information 


The dosexterr function obtains the extended error information returned by the DOS sys- 
tem call INT 0x59 and stores the values in the structure pointed to by errorinfo. This func- 
tion is useful when making system calls under DOS versions 3.0 or later, which offer 
extended error handling. 


The structure type DOSERROR is defined in DOS.H. The DOSERROR structure contains 
the following elements: 


Element Description 

int exterror AX register contents 
char class BH register contents 
char action | BL register contents 
char locus CH register contents 


Giving a NULL pointer argument causes dosexterr to return the value in AX without 
filling in the structure fields. See MS-DOS Encyclopedia (Duncan, ed.; Redmond, WA: 
Microsoft Press, 1988) or Programmer’s PC Sourcebook (Hogan; Redmond, WA: 
Microsoft Press, 1988) for more information on the register contents. 


The dosexterr function returns the value in the AX register (identical to the value in the 
exterror structure field). 
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The dosexterr function should be used only under DOS versions 3.0 or later. 
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See Also perror 


Example 


[* DOSEXERR.C: This program tries to open the file test.dat. If the 

* attempted open operation fails, the program uses dosexterr to display 
* extended error information. 

*/ 


#Hinclude <dos.h> 
#Hinclude <io.h> 
#Hinclude <fcnt1.h> 
dHinclude <stdio.h> 


void main() 

{ 
struct DOSERROR doserror; 
int fd; 


/* Attempt to open a non-existent file */ 
if( (fd = open( "NOSUCHF.ILE", O_RDONLY )) == -1 ) 
{ 
dosexterr( &doserror ); 
printf( "Error: %d Class: 4d Action: %4d Locus: %d\n", 
doserror.exterror, doserror.class, 
doserror.action, doserror.locus ); 
} 
else 
{ 
printf( "Open succeeded so no extended information printed\n" ); 
close( fd ); 


Output 


Error: 2 Class: 8 Action: 3 Locus: 2 


dup, dup2 
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Description Create a second handle for an open file (dup), or reassign a file handle (dup2). 
#include <io.h Required only for function declarations 
int dup( int handle ); 
int dup2( int handlel, int handle2 ); 
handle, handlel Handle referring to open file 
handle2 Any handle value 
Remarks The dup and dup2 functions cause a second file handle to be associated with a currently 


Return Value 


Compatibility 


See Also 


Example 


open file. Operations on the file can be carried out using either file handle. The type of 
access allowed for the file is unaffected by the creation of a new handle. 


The dup function returns the next available file handle for the given file. The dup2 func- 
tion forces handle2 to refer to the same file as handle. If handle2 is associated with an 
open file at the time of the call, that file is closed. 


The dup function returns a new file handle. The dup2 function returns 0 to indicate 
success. Both functions return —1 if an error occurs and set errno to one of the following 
values: 


Value Meaning 
EBADF Invalid file handle 
EMFILE No more file handles available (too many open files) 


O ANS! @& DOS M OS/2 Mi UNIX’ 8B XENIX 


close, creat, open 


/* DUP.C: This program uses the variable old to save the original stdout. 
* Tt then opens a new file named new and forces stdout to refer 
* to it. Finally, it restores stdout to its original state. 


*/ 


#Hinclude <io.h> 


dHinclude <stdlib.h> 
#Hinclude <stdio.h> 


dup, dup2 


void main() 


( 


int old; 
FILE *new; 


old = dup( 1 ); /* “old" now refers to "stdout" */ 
/* Note: file handle 1 == "stdout" */ 
if( old == -1 ) 
{ 
perror( “dup( 1 ) failure” ); 
exit( 1); 
} 
write( old, "This goes to stdout first\r\n", 27 ); 
if( ( new = fopen( "data", "w" ) ) == NULL ) 
{ 
puts( "Can't open file ‘data'\n" ); 
exit( 1); 
} 


/* stdout now refers to file "data" */ 
if( -1 == dup2( fileno( new ), 1 ) ) 
{ 
perror( "Can't dup2 stdout" ); 
exit( 1); 


J 


puts( "This goes to file ‘data'\r\n" ); 


/* Flush stdout stream buffer so it goes to correct file */ 


-fflush( stdout ); 


fclose( new ); 


/* Restore original stdout */ 

dup2( old, 1 ); 

puts( "This goes to stdout\n" ); 
puts( "The file ‘data’ contains:" ); 
system( "type data" ); 


Output 


This goes to stdout first 
This goes to stdout 


The file ‘data’ contains: 
This goes to file ‘data’ 


242 


243 


Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


ecvt 


Converts a double number to a string. 
#include <stdlib.h> Required only for function declarations 


char *ecvt( double value, int count, int *dec, int *sign ); 


value Number to be converted 
count Number of digits stored 

dec Stored decimal-point position 
sign | Sign of converted number 


The ecvt function converts a floating-point number to a character string. The value argu- 
ment is the floating-point number to be converted. The ecvt function stores up to count 
digits of value as a string and appends a null character (’\0’). If the number of digits in 
value exceeds count, the low-order digit is rounded. If there are fewer than count digits, 
the string is padded with zeros. . 


Only digits are stored in the string. The position of the decimal point and the sign of value 
can be obtained from dec and sign after the call. The dec argument points to an integer 
value giving the position of the decimal point with respect to the beginning of the string. A 
O or negative integer value indicates that the decimal point lies to the left of the first digit. 
The sign argument points to an integer indicating the sign of the converted number. If the 
integer value is O, the number is positive. Otherwise, the number is negative. 


The ecvt and fevt functions use a single statically allocated buffer for the conversion. Each 
call to one of these routines destroys the result of the previous call. 
The ecvt function returns a pointer to the string of digits. There is no error return. 
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atof, atoi, atol, fevt, gcvt 


/* ECVT.C: This program uses ecvt to convert a floating-point 
* number to a character string. 


of 


dHinclude <stdlib.h> 
#Hinclude <stdio.h> 
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void main() 
{ 


int decimal, sign; 
char *buffer; 
int precision = 10; 


double source = 3.1415926535; 
buffer = ecvt( source, precision, &decimal, &sign ); 


printf( "source: 42.10f buffer: '%s' decimal: 4d Sign: %d\n", 
_ source, buffer, decimal, sign ); 


Output 


source: 3.1415926535 buffer: '3141592654' decimal: 1 sign: @ 
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Description Draw ellipses. 
#include <graph.h> 


short far _ellipse( short control, short x/, short y/, short x2, short y2 ); 


short far _ellipse_w( short control, double wx/, double wy/, double wx2, 
double wy2 ); 


short far _ellipse_wxy( short control, struct _wxycoord _far *pwxy1, 
struct _wxycoord far *pwxy2 ); 


control Fill flag 

xl, yl Upper-left corner of bounding rectangle 

x2, y2 Lower-right comer of bounding rectangle 
wxl, wyl Upper-left corner of bounding rectangle 

wx2, wy2 Lower-right comer of bounding rectangle 
pwxyl Upper-left corner of bounding rectangle 

pwxy2 Lower-right comer of bounding rectangle 

Remarks The _ ellipse functions draw ellipses or circles. The borders are drawn in the current color. 


In the _ellipse function, the center of the ellipse is the center of the bounding rectangle de- 
fined by the view-coordinate points (x/, y/) and (x2, y2). 


In the _ellipse_w function, the center of the ellipse is the center of the bounding rectangle 
defined by the window-coordinate points (wx/, wyl) and (wx2, wy2). 


In the _ellipse_wxy function, the center of the ellipse is the center of the bounding rec- 
tangle defined by the window-coordinate pairs (pwxy/) and (pwxy2). 


If the bounding-rectangle arguments define a point or a vertical or horizontal line, no fig- 
ure is drawn. 


The control argument can be one of the following manifest constants: 


Constant Action 


_GFILLINTERIOR Fills the ellipse using the current fill mask 
_GBORDER Does not fill the ellipse 
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The control option given by _GFILLINTERIOR is equivalent to a subsequent call to the 
_floodfill function, using the center of the ellipse as the starting point and the current color 
(set by _setcolor) as the boundary color. . 


Return Value The _ ellipse functions return a nonzero value if the ellipse is drawn successfully; other- 
wise, they return 0. 


Compatibility O ANS! @ DOS O oS2 CO UNIX O XENKX 


See Also _arc functions, _floodfill, _grstatus, _lineto functions, _pie functions, 
_polygon functions, _rectangle functions, _setcolor, _setfillmask 


Example 
/* ELLIPSE.C: This program draws a simple ellipse. */ 


#Hinclude <conio.h> 
dHinclude <stdlib.h> 
#Hinclude <graph.h> 


void main() 
{ 
/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_ellipse( _GFILLINTERIOR, 88, 58, 240, 158 ); 
/* Strike any key to clear screen. */ 


getch(); 
_setvideomode( _DEFAULTMODE ); 
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_ enable 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Enables interrupts. 

#include <dos.h> 

void _enable( void ); 

The _enable routine enables interrupts by executing an 8086 STI machine instruction. 
None. 

O ANSi M@ DOS OF os 0 UNIX QO XENIX 


_ disable ‘ 
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Description Terminates an Os/2 thread. 
#include <process.h> Multithread version of PROCESS.H 
void far _endthread( void ); 
Description The _endthread function terminates a thread eceated by _beginthread. 


Because threads terminate automatically, the _endthread function is normally not re- 
quired. It is used to terminate a thread conditionally. 


The OS/2 function DosExit should not be used to terminate threads created by the 
_beginthread function. If DosExit is used, the results are unpredictable. 

Return Value None. ‘ 

Compatibility O ANS! OF DOS WM OS/ O UNIX OO XENIX 


See Also _beginthread 


Example See the example for _beginthread. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


eof 


Tests for end-of-file. 

#include <io.h> Required only for function declarations 
int eof( int handle ); 

handle Handle referring to open file 


The eof function determines whether the end of the file associated with handle has been 
reached. 


The eof function returns the value 1 if the current position is end-of-file, or 0 if it is not. A 
return value of —1 indicates an error; in this case, errno is set to EBADF, indicating an 
invalid file handle. 
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clearerr, feof, ferror, perror 


/* EOF.C: This program reads data from a file ten bytes at a time 
* until the end of the file is reached or an error is encountered. 


mf 


fHinclude <io.h> 


dHinclude <fcntl.h> 
dHinclude <stdio.h> 
fHinclude <stdlib.h> 


void main() 


{ 


int fh, count, total = @; 


char buf[19]; 


if( (fh = open( “eof.c", O_RDONLY )) == - 1 ) 


exit( 1 ); 
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/*° Cycle until end of file reached: */ 
while( !eof( fh ) ) 
{ 
/* Attempt to read in 1@ bytes: */ 
if( (count = read( fh, buf, 18 )) == -1 ) 
{ 7 
perror( "Read error" ); 
break; 
} 


/* Total up actual bytes read */ 

total += count; 
} 
printf( "Number of bytes read = %d\n", total ); 
close( fh ); 


Output 


Number of bytes read = 715 
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exec Functions 


Description 


Remarks 


Load and execute new child processes. 
#include <process.h> Required only for function declarations 


int execl( char *cmdname, char *arg0, ... char *argn, NULL); 

int execle( char *cmdname, char *arg0, ... char *argn, NULL, char **envp ); 
int execlp( char *cmdname, char *arg0, ... char *argn, NULL ); 

int execlpe( char *cmdname, char *arg0, ... char *argn, NULL, char **envp ); 
int execv( char *cmdname, char **argy ); 

int execve( char *cmdname, char **argy, char **envp ); 

int execvp( char *cmdname, char **argv ); 


int execvpe( char *cmdname, char **argy, char **erwvp ); 


cmdname Path name of file to be executed 
arg0, ... argn List of pointers to arguments 
argv Array of pointers to arguments 


envp Array of pointers to environment settings 


The exec functions load and execute new child processes. When the call is successful in 
DOS, the child process is placed in the memory previously occupied by the calling 
process. Under OS/2, calling an exec function is equivalent to calling the corresponding 
function with the P NOWAITO argument specified, followed by a call to the exit function. 
Sufficient memory must be available for loading and executing the child process. 


All of the exec functions use the same operating system function. The letter(s) at the end 
of the function name determine the specific variation, as shown in the following list: 


Letter Variation 

e . An array of pointers to environment arguments is explicitly 
passed to the child process. 

| Command-line arguments are passed individually to the exec 
function. 

p Uses the PATH environment variable to find the file to be 
executed. 

Vv Command-line arguments are passed to the exec function as 


an array of pointers. 
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The cmdname argument specifies the file to be executed as the child process. It can specify 
a full path (from the root), a partial path (from the current working directory), or just a file 
name. If cmdname does not have a file-name extension or does not end with a period (.), 
the exec function searches for the named file; if the search is unsuccessful, it tries the same 
base name, first with the extension .COM, then with the extension .EXE. If cmdname has 
an extension, only that extension is used in the search. If cmdname ends with a period, the 
exec calls search for cmdname with no extension. The execlp, execlpe, execvp, and 
execvpe routines search for cmdname (using the same procedures) in the directories 
specified by the PATH environment variable. 


If cmdname contains a drive specifier or any slashes (i.e., if it is a relative path name), the 
exec call searches only for the specified file and no path searching is done. 


Arguments are passed to the new process by giving one or more pointers to character 
strings as arguments in the exec call. These character strings form the argument list for the 
child process. The combined length of the strings forming the argument list for the new 

_ process must not exceed 128 bytes (in real mode only). The terminating null character 
(’\0’) for each string is not included in the count, but space characters (inserted automat- 
ically to separate the arguments) are counted. 


The argument pointers can be passed as separate arguments (execl, execle, execlp, and 
execlpe) or as an array of pointers (execv, execve, execvp, and execvpe). At least one ar- 
gument, arg0, must be passed to the child process; this argument is argv[0] of the child 
process. Usually, this argument is a copy of the cmdname argument. (A different value 
will not produce an error.) Under versions of DOS earlier than 3.0, the passed value of 
arg0 is not available for use in the child process. However, under OS/2 and under DOS 
versions 3.0 and later, cmdname is available as arg0. 


The execl, execle, execlp, and execlpe calls are typically used when the number of argu- 
ments is known in advance. The argument arg0 is usually a pointer to cmdname. The argu- 
ments arg/ through argn point to the character strings forming the new argument list. A 
null pointer must follow argn to mark the end of the argument list. 


The execv, execve, execvp, and execvpe calls are useful when the number of arguments to 
the new process is variable. Pointers to the arguments are passed as an array, argv. The ar- 
gument argyv[0] is usually a pointer to cmdname. The arguments argv[1] through argv[n] 
point to the character strings forming the new argument list. The argument argv[n+1] must 
be a NULL pointer to mark the end of the argument list. 


Files that are open when an exec call is made remain open in the new process. In the execl, 
execlp, execv, and execvp calls, the child process inherits the environment of the parent. 
The execle, execlpe, execve, and execvpe calls allow the user to alter the environment for 
the child process by passing a list of environment settings through the envp argument. The 
argument envp is an array of character pointers, each element of which (except for the 
final element) points to a null-terminated string defining an environment variable. Such a 
string usually has the form 
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exec Functions 


Return Value 


NAME=value 


where NAME is the name of an environment variable and value is the string value to which 
that variable is set. (Note that value is not enclosed in double quotation marks.) The final 
element of the envp array should be NULL. When envp itself is NULL, the child process in- 
herits the environment settings of the parent process. 


A program executed with one of the exec family of functions is always loaded into 
memory as if the “maximum allocation” field in the program’s .EXE file header is set to 
the default value of OFFFFH. You can use the EXEMOD utility to change the maximum 
allocation field of a program; however, such a program invoked with one of the exec func- 
tions may behave differently from a program invoked directly from the operating-system 
command line or with one of the spawn functions. 


The exec calls do not preserve the translation modes of open files. If the child process 
must use files inherited from the parent, the setmode routine should be used to set the 
translation mode of these files to the desired mode. 


You must explicitly flush (using fflush or flushall) or close any stream prior to the exec 
function call. 


Signal settings are not preserved in child processes that are created by calls to exec 
routines. The signal settings are reset to the default in the child process. 


The exec functions do not normally return to the calling process. If an exec function re- 
turns, an error has occurred and the return value is —1. The errno variable is set to one of 
the following values: . 


Value Meaning 

E2BIG The argument list exceeds 128 bytes, or the space required for 
the environment information exceeds 32K. 

EACCES The specified file has a locking or sharing violation 
(OS/2, and DOS versions 3.0 or later). 

EMFILE Too many files open (the specified file must be opened to de- 
termine whether it is executable). 

ENOENT File or path name not found. 

ENOEXEC The specified file is not executable or has an invalid 


executable-file format. 


ENOMEM Not enough memory is available to execute the child process; 
or the available memory has been corrupted; or an invalid 
block exists, indicating that the parent process was not allo- 
cated properly. 
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Compatibility O ANS! @ DOS WW OS/2 WM UNIX @ XENIX 


Because of differences in DOS versions 2.0 and 2.1, child processes generated by the exec 
family of functions (or by the equivalent spawn functions with the P_OVERLAY argu- 
ment) may cause fatal system errors when they exit. If you are running DOS 2.0 or 2.1, 
you must upgrade to DOS version 3.0 or later to use these functions. 


‘Bound programs cannot use the exec family of functions in real mode. 


See Also abort, atexit, exit, exit, onexit, spawn functions, system 


Example 


/* EXEC.C: This program accepts a number in the range 1 through 8 from the 
* command line. Based on the number it receives, it executes one of the 

* eight different procedures that spawn the process named child. For 

* some of these procedures, the child.exe file must be in the same 

* directory; for others, it need only be in the same path. 


#Hinclude <stdio.h> 
#Hinclude <process.h> 


char *my_env[] = { 
"THIS=environment will be", 
"PASSED=to child.exe by the", 
"EXECLE=and", 
"EXECLPE=and", 
"EXECVE=and", 
"EXECVPE=functions”, 
NULL 
3 


void main( int argc, char *argv[] ) 
{ 

char *args[4]; 

int result; 


args{@] = "child"; /* Set up parameters to send */ 
args(1] "execv??"; 

args[2] "two"; 

args[3] NULL; 
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switch( argv({1)](@] ) /* Based on first letter of argument */ 
{ 
case ‘l': 
execl( argv[2], argv[2], “execl", “two", NULL ); 
break; 
case ‘2': 
execle( argv[2], argv[2], "“execle", "two", NULL, my_env ); 
break; 
case '3': ; 
execip( argv([2], argv[2], “execlp", "two", NULL ); 
break; 
case ‘4'; 
execlpe( argv[2], argv{2], "“execipe", "two", NULL, my_env ); 
break; 
case '5': 
execv( argv{2j, args ); 
break; 
case '6': 
execve( argv[2], args, my_env ); 
break; 
case '7'; 
execvp( argv[2], args ); 
break; 
case '8'; 
execvpe( argv[2], args, my_env ); 
break; 
default: 
printf( "SYNTAX: EXEC <1-8> <childprogram>\n" ); 
exit( 1 ); 
} 
printf( "Process was not spawned.\n" ); 
printf( “Program ‘child’ was not found." ); 
} 
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Description — Terminate the calling process after cleanup (exit) or immediately (_ exit). 
#include <process.h> Required only for function declarations 
#include <stdlib.h> Use either PROCESS.H or STDLIB.H 


void exit( int status ); 


void _exit( int status ); 
status Exit status 


Remarks The exit and _ exit functions terminate the calling process. The exit function first calls, in 
LIFO (last-in—first-out) order, the functions registered by atexit and onexit, then flushes 
all file buffers before terminating the process. The _exit function terminates the process 
without processing atexit or onexit functions or flushing stream buffers. The status value 
is typically set to 0 to indicate a normal exit and set to some other value to indicate an 
error. 


Although the exit and _ exit calls do not return a value, the low-order byte of status is 
made available to the waiting parent process, if one exists, after the calling process exits. 
The status value is available to the operating-system batch command ERRORLEVEL. 


The behavior of the exit, exit, cexit, and _c_exit functions is as follows: 


Function Action 


exit ' Performs complete C library termination procedures, termi- 
nates the process, and exits with the supplied status code. 


_exit Performs “quick” C library termination procedures, terminates 
the process, and exits with the supplied status code. 


_cexit Performs complete C library termination procedures and re- 
turns to caller, but does not terminate the process. 


_c exit Performs “quick” C library termination procedures and re- 
turns to caller, but does not terminate the process. 
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exit, exit 


Return Value 


Compatibility 


See Also 


Example 
/*® EXITER.C: Thi 


None. 


exit 
M@ANS| @ DOS # OS/ WUNIX’ WB XENIX 
_exit 


O ANS! M@ DOS MOS QO UNIX O XENIX 


abort, atexit, cexit, exec functions, onexit, spawn functions, system 


S program prompts the user for a yes or no and returns 


* a DOS error code of 1 if the user answers Y or y; otherwise it | 
* returns @. The error code could be tested in a batch file. 


x/ Hy 


dFinclude <conio. 


h> 


dHinclude <stdlib.h> 


void main() 


{ . 
char ch; 


cputs( "Yes or no? " ); 


ch = getch(); 
cputs( “\r\n" 
if( toupper( 
exit( 1 ); 
else 
exit( 0 ); 


); 
ch. ae" 
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Description Calculate the exponential. 
#include <math.h> 


double exp( double x ); 
long double expl( long double x ); 


x Floating-point value 
Remarks The exp and expl functions return the exponential function of their floating-point argu- 
ments (x). 


The expl function is the 80-bit counterpart; it uses an 80-bit, 10-byte coprocessor form of 
arguments and return values. See the reference page on the long double functions for more 
details on this data type. 


Return Value These functions return e*. The functions return HUGE_VAL on overflow and set errno to 
ERANGE; on underflow, they return 0 but do not set errno. 


Compatibility exp 
MANS! @ DOS #8 OS/2 UNIX’ WF XENIX 
expl 


O ANS| @ DOS mos? O UNX Oj XENIX 


See Also log functions 


Example 


/*® EXP.C */ 
#include <math.h> 
dHinclude <stdio.h> 
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void main() 
{ 
double x = 2.302585093, y; 


y = exp( x ); 


printf( “exp( 4f ) = 4f\n", x, y ); 
} 


Output 


exp( 2.302585 ) = 10.800000 
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Description 


Remarks 


Changes the size of a memory block. 
#include <malloc.h> Required only for function declarations 


void *_expand( void *memblock, size_t size ); 


void _based( void ) *_bexpand(_segment seg, void _based( void ) *memblock, 
size_t size ); 


void far *_fexpand( void _far *memblock, size_t size ); 


void _near *_nexpand( void _near *memblock, size_t size ); 


memblock Pointer to previously allocated memory block 
size New size in bytes 
seg Value of base segment 


The _expand family of functions changes the size of a previously allocated memory block 
by attempting to expand or contract the block without moving its location in the heap. The 
memblock argument points to the beginning of the block. The size argument gives the new 
size of the block, in bytes. The contents of the block are unchanged up to the shorter of the 
new and old sizes. 


The memblock argument can also point to a block that has been freed, as long as there has 
been no intervening call to calloc, expand, malloc, or realloc. If memblock points to a 
freed block, the block remains free after a call to one of the _expand functions. 


The seg argument is the segment address of the _based heap. 


In large data models (compact-, large-, and huge-model programs), _expand maps to 
_fexpand. In small data models ( tiny-, small-, and medium-model programs), expand 
maps to _nexpand. 


The various _expand functions change the size of the storage block in the data segments 
shown in the list below: 


Function Data Segment 

_expand Depends on data model of program 

_bexpand Based heap specified by seg, or in all based heaps if seg 
is zero 

_fexpand Far heap (outside default data segment) 


_nexpand Near heap (inside default data segment) 
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_ expand Functions 


Return Value 


Compatibility 


See Also 


Example 


/* EXPAND.C */ 
#Finclude <stdio.h> 
#Hinclude <malloc.h> 
dFinclude <stdlib.h> 


void main() 


( 


The expand family of functions returns a void pointer to the reallocated memory 
block. Unlike realloc, expand cannot move a block to change its size. This means the 
memblock argument to _expand is the same as the return value if there is sufficient 
memory available to expand the block without moving it. 


With the exception of the _bexpand function, these functions return NULL if there is in- 
sufficient memory available to expand the block to the given size without moving it. The 
_bexpand function returns NULLOFF if insufficient memory is available. The item 
pointed to by memblock will have been expanded as much as possible in its current 
location. 


The storage space pointed to by the return value is guaranteed to be suitably aligned for 
storage of any type of object. The new size of the item can be checked with the _msize 
function. To get a pointer to a type other than void, use a type cast on the return value. 


O ANS! @ DOS WM OS/2 OF UNIX OF XENIX 


calloc functions, free functions, malloc functions, _msize functions, realloc functions 


char *bufchar; 


printf( "Allocate a 512 element buffer\n" ); 


if( (bufchar 
exit( 1); 


= (char *)calloc( 512, sizeof( char ) )) == NULL ) 


printf( “Allocated %d bytes at %Fp\n", 


_msize( 


if( (bufchar 


bufchar ), (void _far *)bufchar ); 


= (char *)_expand( bufchar, 1024 )) == NULL ) 


printf( "Can't expand" ); 


else 


printf( "Expanded block to 4d bytes at %Fp\n", 


_msi 


ze( bufchar ), (void _far *)bufchar ); 


/* Free memory */ 
free( bufchar ); 


exit( @ ); 
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Output 


Allocate a 512 element buffer 
Allocated 512 bytes at 0@67:142A 
Expanded block to 1024 bytes at @@67:142A 
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fabs, fabs! 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Calculate the absolute value of their floating-point arguments. 
#include <math.h> 


double fabs( double + ); 
long double fabsl( long double x ); 


x Floating-point value 


The fabs and fabsl functions calculate the absolute value of their floating-point arguments. 


The fabs] function is the 80-bit counterpart; it uses an 80-bit, 10-byte coprocessor form of 
arguments and return values. See the reference page on the long double functions for more 
details on this data type. 


These functions return the absolute value of their arguments. There is no error return. 


fabs 


MANS} M DOS  OS/2 Mf UNIX. Mf XENIX 


fabsl 
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abs, cabs, labs 


/* ABS.C: This program computes and displays the absolute values of 
* several numbers. 


iad 


dFinclude <stdio.h> 
#Hinclude <math.h> 
dHinclude <stdlib.h> 
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void main() 

{ 
int ix = -4, iy; 
Tong 1x = -41567L, ly; 
double dx = -3.141593, dy; 


iy = abs( ix ); 
printf( "The absolute value of %d is %d\n", ix, iy); 


ly = labs( 1x ); 
printf( "The absolute value of %1d is 21d\n", 1x, ly); 


dy = fabs( dx ); 
printf( "The absolute value of 4f is 2f\n", dx, dy ); 


Output 


The absolute value of -4 is 4 
The absolute value of -41567 is 41567 
The absolute value of -3.141593 is 3.141593 
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Description Closes a stream (fclose) or closes all open streams (fcloseall). 
#include <stdio.h> 


int fclose( FILE *stream ); 


int fcloseall( void ); 
stream Pointer to FILE structure 


Remarks The fclose function closes stream. The fcloseall function closes all open streams except 
stdin, stdout, stderr (and in DOS, stdaux and stdprn),. It also closes and deletes any tem- 
porary files created by tmpfile. 


In both functions, all buffers associated with the stream are flushed prior to closing. 
System-allocated buffers are released when the stream is closed. Buffers assigned by the 
user with setbuf and setvbuf are not automatically released. 


Return Value The fclose function returns 0 if the stream is successfully closed. The fcloseall function re- 
turns the total number of streams closed. Both functions return EOF to indicate an error. 


Compatibility fclose 
@ ANS! @ DOS W@W OS/2 HE UNIX WB XENIX 
fcloseall 


O ANS! @ DOS HM oOS/2 OO UNIX OC XENIX 


See Also close, fdopen, fflush, fopen, freopen 


Example 

/* FOPEN.C: This program opens files named "data" and "“data2". It uses 
* fclose to close “data" and fcloseall to close all remaining files. 
*/ 


dHinclude <stdio.h> 
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FILE *stream, *stream2; 


void main() 
{ 
int numclosed; 


/* Open for read (will fail if ‘data does not exist) */ 
if( (stream = fopen( "data", "r" )) == NULL ) 

printf( "The file ‘data’ was not opened\n" ); 
else 

printf( "The file ‘data’ was opened\n" ); 


/* Open for write */ 
if( (stream2 = fopen( "data2", "wt" )) == NULL ) 
printf( "The file ‘data2' was not opened\n" ); 
else 
printf( "The file ‘data2' was opened\n" ); 


/* Close stream */ 
if( fclose( stream ) ) 
printf( "The file ‘data’ was not closed\n" ); 


/* All other files are closed: */ 
numclosed = fcloseall( ); 
printf( "Number of files closed by fcloseall: Z%u\n", numclosed ); 


Output 


The file ‘data’ was opened 
The file ‘data2' was opened 
Number of files closed by fcloseall: 1 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


, Example 


fevt 


Converts a floating-point number to a string. 
#include <stdlib.h> Required only for function declarations 


char “fevt( double value, int count, int *dec, int *sign ); 


value Number to be converted 

count Number of digits after decimal point 
dec Pointer to stored decimal-point position 
sign Pointer to stored sign indicator 


The fevt function converts a floating-point number to a null-terminated character string. 
The value argument is the floating-point number to be converted. The fevt function stores 
the digits of value as a string and appends a null character (’\0’). The count argument speci- 
fies the number of digits to be stored after the decimal point. Excess digits are rounded off 
to count places. If there are fewer than count digits of precision, the string is padded with 
zeros. 


Only digits are stored in the string. The position of the decimal point and the sign of value 
can be obtained from dec and sign after the call. The dec argument points to an integer 
value; this integer value gives the position of the decimal point with respect to the begin- 
ning of the string. A zero or negative integer value indicates that the decimal point lies to 
the left of the first digit. The argument sign points to an integer indicating the sign of 
value. The integer is set to 0 if value is positive and is set to a nonzero number if value is 
negative. 


The ecvt and fevt functions use a single statically allocated buffer for the conversion. Each 
call to one of these routines destroys the results of the previous call. 
The fevt function returns a pointer to the string of digits. There is no error return. 


O ANS! M@ DOS WM OS/2 MW UNIX Mf XENIX 


atof, atoi, atol, ecvt, gcvt 


/* FCVT.C: This program converts the constant 3.1415926535 to a string and 
* sets the pointer *buffer to point to that string. 


i 
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#Hinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main() 
{ 
int decimal, sign; 
char *buffer; 
double source = 3.1415926535; 


buffer = fcvt( source, 7, &decimal, &sign ); 


printf( “source: %2.10f buffer: ‘%s' decimal: %d Sign: %d\n", 
source, buffer, decimal, sign ); 


Output 


source: 3.1415926535 buffer: '31415927' decimal: 1 sign: @ 


269 


Description 


Remarks 


fdopen 


Opens a stream using a handle. 
#include <stdio.h> 
FILE *fdopen( int handle, char *mode ); 


handle Handle referring to open file 


mode Type of access permitted 


The fdopen function associates an input/output stream with the file identified by handle, 
thus allowing a file opened for “low-level” I/O to be buffered and formatted. (See Section 
2.7, “Input and Output,” for an explanation of stream I/O and low-level I/O.) The mode 
character string specifies the type of access requested for the file, as shown below. The fol- 
lowing list gives the mode string used in the fopen and fdopen functions and the corre- 
sponding oflag arguments used in the open and sopen functions. A complete description 
of the mode string argument is given in the remarks section of the fopen function. 


Type String Equivalent Value for open/sopen 

pit O_RDONLY 

"w" O_WRONLY (usually O_WRONLY | O_CREAT | O_TRUNC) 

nar O_WRONLY | 0_APPEND (usually O_WRONLY | O_CREAT | 
O_APPEND) 

Mp O_RDWR 

"w+" O_RDWR (usually O_RDWR | O_CREAT | O_TRUNC) 

"a+" O_RDWR | O_APPEND (usually O_RDWR | O_APPEND | 
O_CREAT ) 


In addition to the values listed above, one of the following characters can be included in 
the mode string to specify the translation mode for newlines. These characters correspond 
to the constants used in the open and sopen functions, as shown below: 


Mode Equivalent Value for open/sopen 
t O TEXT 
b O_BINARY 


If t or b is not given in the mode string, the translation mode is defined by the default- 
mode variable _fmode. 
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The t option is not part of the ANSI standard for fopen and fpopen, but is instead a 
Microsoft extension and should not be used where ANSI portability is desired. 


Return Value The fdopen function returns a pointer to the open stream. A null pointer value indicates an 
error. 

Compatibility O ANS! WM DOS HW OS/2 WF UNIX’ Mf XENIX 

See Also dup, dup2, fclose, fcloseall, fopen, freopen, open 

Example 


/* FDOPEN.C: This program opens a file using low-level 1/0, then uses 
* fdopen to switch to stream access. It counts the lines in the file. 
*/ 


#Hinclude <stdlib.h> 
#Hinclude <stdio.h> 

#Hinclude <fcntl.h> 

#Hinclude <io.h> 


void main() 

{ 
FILE *stream; 
int fh, count = @; 
char inbuf[128]; 


/* Open a file handle. */ 
if( (fh = open(."fdopen.c", O_RDONLY )) == -1 ) 
exit( 1 ); 


/* Change handle access to stream access. */ 
if( (stream = fdopen( fh, "r" )) == NULL ) 
exit( 1 ); 


while( fgets( inbuf, 128, stream ) != NULL ) 
count++; 
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/* After fdopen, close with fclose, not close. */ 
fclose( stream ); 


printf( “Lines in file: %d\n", count ); 


Output 


Lines in file: 31 
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Description Tests for end-of-file on a stream. 

#include <stdio.h> 

int feof( FILE *stream );_. 

stream Pointer to FILE structure 


Remarks The feof routine (implemented as a macro) determines whether the end of stream has been 
reached. Once the end of the file is reached, read operations return an end-of-file 
indicator until the stream is closed or until rewind, fsetpos, fseek, or clearerr is called 
against it. 


Return Value §——- The feof function returns a nonzero value after the first read operation that attempts to read 
past the end of the file. It returns 0 if the current position is not end-of-file. There is no 
error return. 


Compatibility MANS! @ DOS WW OS/7 WW UNIX @ XENIX 


See Also clearerr, eof, ferror, perror 


Example 


/* FEOF.C: This program uses feof to indicate when it reaches the end 
* of the file FEOF.C. It also checks for errors with ferror. 
*/ 


dfinclude <stdio.h> 
dHinclude <stdlib.h> 


void main() 

{ 
int count, total = @; 
char buffer[109]; 
FILE *stream; 


if( (stream = fopen( "“feof.c", "r" )) == NULL ) 
Oxdt(. 2). 
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/* Cycle until end of file reached: */ 
while( !feof( stream ) ) 
{ 
/* Attempt to read in 18 bytes: */ 
count = fread( buffer, sizeof( char ), 180, stream ); 
if( ferror( stream ) ) 
{ 
perror( "Read error" ); 
break; 


) 


/* Total up actual bytes read */ 
total += count; 
} 
printf( "Number of bytes read = %4d\n", total ); 
fclose( stream ); 
} 


Output 


Number of bytes read = 697 


ferror | 274 


2 SS PS SS TP SS SO PET 
Description Tests for an error on a stream. 

#include <stdio.h> 

int ferror( FILE *stream ); 

Stream Pointer to FILE structure 


Remarks The ferror routine (implemented as a macro) tests for a reading or writing error on the file 
associated with stream. If an error has occurred, the error indicator for the stream remains 
set until the stream is closed or rewound, or until clearerr is called against it. 


Return Value If no amar has occurred on stream, ferror returns 0. Otherwise, it returns a nonzero value. 
Compatibility mM ANS! @ DOS @# OS/2 UNIX. Mt XENIX 

See Also clearerr, eof, feof, fopen, perror 

Example 


/* FEOF.C: This program uses feof to indicate when it reaches the end 
* of the file FEOF.C. It also checks for errors with ferror. 
*/ 


#Hinclude <stdio.h> 
fHinclude <stdlib.h> 


void main() 

{ 
int count, total = @; 
char buffer[10@]; 
FILE *stream; 


if( (stream = fopen( “feof.c", "r" )) == NULL ) 
exit( 1); 
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/* Cycle until end of file reached: */ 
while( !feof( stream ) ) 
{ 
/* Attempt to read in 18 bytes: */ 
count = fread( buffer, sizeof( char ), 100, stream ); 
if( ferror( stream ) ) 
( 
perror( “Read error" ); 
break; 
} 


/* Total up actual bytes read */ 
total += count; 


} 
printf( “Number of bytes read = d\n", total ); 
fclose( stream ); 


Output 


Number of bytes read = 697 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


/* FFLUSH.C */ 


Flushes a stream. 

#include <stdio.h> 

int fflush( FILE *stream ); 

stream Pointer to FILE structure 


If the file associated with stream is open for output, fflush writes to that file the contents 
of the buffer associated with the stream. If the stream is open for input, fflush clears the 
contents of the buffer. The fflush function negates the effect of any prior call to ungete 
against stream. 


Buffers are automatically flushed when they are full, when the stream is closed, or when a 
program terminates normally without closing the stream. 


The stream remains open after the call. The fflush function has no effect on an unbuffered 
stream. 


The fflush function returns the value 0 if the buffer was successfully flushed. The value 0 
is also returned in cases in which the specified stream has no buffer or is open for reading 
only. A return value of EOF indicates an error. 


MANS! @ DOS M OS/2 W UNIX” WW XENIX 


fclose, flushall, setbuf 


dHinclude <stdio.h> 
#tinclude <conio.h> 


void main() 


int integer; 


char string[81]; 
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/* Read each word as a string. */ 
printf( “Enter a sentence of four words with scanf: " ); 
for( integer = 0; integer < 4; integert++ ) 

scanf( "%s", string ); 

printf( "%s\n", string ); 


/* You must flush the input buffer before using gets. */ 
fflush( stdin ); 

printf( "Enter the same sentence with gets: " ); 
gets( string ); 

printf( "“%s\n", string ); 


/ 


Output 


Enter a sentence of four words with scanf: This is a test 
This 

is 

a ‘ 

test 

Enter the same sentence with gets: This is a test 

This is a test 
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Description Read a character from a stream (fgetc) or stdin (fgetchar). 
#include <stdio.h> 


int fgetc( FILE *stream ); 
int fgetchar( void ); 


stream | Pointer to FILE structure 


Remarks The fgete function reads a single character from the current position of the file associated 
with stream. The character is converted and returned as an int. The function then incre- 
ments the associated file pointer (if any) to point to the next character. The fgetchar func- 
tion is equivalent to fgetc(stdin). 


The fgete and fgetchar routines are identical to getc and getchar, but they are functions 
rather than macros. 


r 

Return Value The fgetc and fgetchar functions return the character read. They return EOF to indicate an 
error or end-of-file. Use feof or ferror to distinguish between an error and an end-of-file 
condition. 

Compatibility fgetc 
M@ ANS| M@ DOS WM OS WW UNIX’ MI XENIX 


fgetchar 


O ANS! M@ DOS MOS/2 O UNIX OI XENIX 


See Also fputc, fputchar, getc, getchar 


Example 


/* FGETC.C: This program uses getc to read the first 8@ input characters 
* (or until the end of input) and place them into a string named buffer. 
*/] 


dFinclude <stdio.h> 
#Hinclude <stdlib.h> 
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void main() 

{ 
FILE *stream; 
char buffer[81]; 
int i, ch; 


/* Open file to read line from: */ 
if( (stream = fopen( "fgetc.c", "r" )) == NULL ) 
exit( @ ); 


/* Read in first 80 characters and place them in "buffer": */ 
ch = fgetc( stream ); 
for( i=@; (i < 80 ) && ( feof( stream ) == @ ); i++ ) 
{ 
buffer{i] = ch; 
ch = fgetc( stream ); 
} 
/* Add null to end string */ 
bufferCli] = '\@'; 
printf( “%s\n", buffer ); 
fclose( stream ); 


— Output 


/* FGETC.C: This program uses getc to read the first 80 input characters 
= LOr 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Gets a stream’s file-position indicator. 
#include <stdio.h> 
int fgetpos( FILE *stream, fpos_t *pos ); 


stream Target stream 


pos — Position-indicator storage 


The fgetpos function gets the current value of the stream argument’s file-position indicator 
and stores it in the object pointed to by pos. The fsetpos function can later use information 


_ Stored in pos to reset the stream argument’s pointer to its position at the time fgetpos was 


called. 


The pos value is stored in an internal format and is intended for use only by the fgetpos 
and fsetpos functions. 


If successful, the fgetpos function returns 0. On failure, it returns a nonzero value and sets 
errno to one of the following manifest constants (defined in STDIO.H): 


Constant Meaning 

EBADF The specified stream is not a valid file handle or is not 
accessible. 

EINVAL The stream value is invalid. 


MANS! @ DOS M OS/72 OO UNIX OC XENIX 


fsetpos 


/* FGETPOS.C: This program opens a file and reads bytes at several 
* different locations. 


Bes 


dHinclude <stdio.h> 
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void main() 


{ 


FILE *stream; 
fpos_t pos; 

int val; 

char buffer{20]; 


if( (stream = fopen( "fgetpos.c", “rb” )) == NULL ) 
printf( “Trouble opening file\n" ); 
else 
{ 
/* Read some data and then check the position. */ 
fread( buffer, sizeof( char ), 10, stream ); 
if( fgetpos( stream, &pos ) != @ ) 
perror( "“fgetpos error" ); 
else 
{ 
fread( buffer, sizeof( char ), 10, stream ); 
printf( "10 bytes at byte 41d: %.10s\n", pos, buffer ); 
} 


/* Set a new position and read more data */ 
pos = 140; 
if( fsetpos( stream, &pos ) != @ ) 

perror( "fsetpos error" ); 


fread( buffer, sizeof( char ), 10, stream ); 
printf( "10 bytes at byte 41d: %.10s\n", pos, buffer ); 


fclose( stream ); 


Output 


10 bytes at byte 10: .C: This p 
1@ bytes at byte 140: FILE. << 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets a string from a stream. 
#include <stdio.h> 


char “fgets( char “string, int n, FILE *stream ); 


string Storage location for data 
n Number of characters stored 
stream Pointer to FILE structure 


The fgets function reads a string from the input stream argument and stores it in string. 
Characters are read from the current stream position up to and including the first newline 


character (’\n’), up to the end of the stream, or until the number of characters read is equal 


to n—1, whichever comes first. The result is stored in string, and a null character (’\0’) is 
appended. The newline character, if read, is included in the string. If n is equal to 1, string 
is empty (‘""). The fgets function is similar to the gets function; however, gets replaces the 
newline character with NULL. 


If successful, the fgets function returns string. It returns NULL to indicate either an error or 
end-of-file condition. Use feof or ferror to determine whether an error occurred. 


MANS! M@ DOS #8 OS/2 ME UNIX @ XENIX 


fputs, gets, puts 


/* FGETS.C: This program uses fgets to display a line from a file on the 


* screen. 
* / 


#Hinclude <stdio.h> 


FILE *stream; 


void main() 
{ 


char line[1@0], *result; 
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a 
if( (stream = fopen( “fgets.c", "r" )) != NULL ) 


{ 
if( fgets( line, 108, stream ) == NULL) 


printf( “fgets error\n" ); 


else 
printf( “%s", line); 
fclose( stream ); 


Output 
/* FGETS.C: This program uses fgets to display a line from a file on the 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Convert floating-point numbers between IEEE and Microsoft binary formats. 
#include <math.h> 


int fieeetomsbin( float *src4, float *dst4 ); 


int fmsbintoieee( float *src4, float *dst4 ); 


scr4 Value to be converted 


dst4 Converted value 


The fieeetomsbin routine converts a single-precision floating-point number in IEEE (Insti- 
tute of Electrical and Electronic Engineers) format to Microsoft (MS) binary format. 


The fmsbintoieee routine converts a floating-point number in Microsoft binary format to 
IEEE format. 


These routines allow C programs (which store floating-point numbers in the IEEE format) 
to use numeric data in random-access data files created with Microsoft BASIC (which 
stores floating-point numbers in the Microsoft binary format), and vice versa. 


The argument src4 points to the float value to be converted. The result is stored at the loca- 
tion given by dst4. 


These routines do not handle IEEE NANs (“not a number”) and infinities. IEEE denormals 
are treated as 0 in the conversions. 


These functions return 0 if the conversion is successful and 1 if the conversion causes an 
overflow. 


O ANS! @ DOS #MOS/2 O UNIX OC XENIX 
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285 


filelength 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets the length of a file. 

#include <io.h> Required only for function declarations 
long filelength( int handle ); 

handle Target file handle 


The filelength function returns the length, in bytes, of the target file associated with 
handle. 


The filelength function retums the file length in bytes. A return value of —1L indicates an 
error, and an invalid handle sets errno to EBADF. 


O ANS! @ DOS # OS/72 OF UNIX OF XENIX 


chsize, fileno, fstat, stat 


/* CHSIZE.C: This program uses filelength to report the size of a 
* file before and after modifying it with chsize. 


*/ 


#Hinclude <io.h> 


dtinclude <fcnt1l.h> 
#Hinclude <sys\types.h> 
#Hinclude <sys\stat.h> 
dHinclude <stdio.h> 


void main() 


{ 


int fh, result; 
unsigned int nbytes = BUFSIZ; 
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/* Open a file */ 
if( (fh = open( "data", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 ) 
{ 
printf( “File length before: %1d\n", filelength( fh ) ); 
if( chsize( fh, 329678 ) == @ ) 
printf( "Size successfully changed\n" ); 
else 
printf( “Problem in changing the size\n" ); 
printf( "File length after: %id\n", filelength( fh ) ); 
close( fh ); 


Output 


File length before: @ 
Size successfully changed 
File length after: 329678 
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fileno 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets the file handle associated with a stream. 
#include <stdio.h> 

int fileno( FILE *stream ); 

stream Pointer to FILE structure 


The fileno routine returns the file handle currently associated with stream. This routine is 
implemented as a macro. 


The fileno routine returns the file handle. There is no error return. The result is undefined 
if stream does not specify an open file. 


O ANS! @ DOS WM OS/2 WM UNIX Mi XENIX 


fdopen, filelength, fopen, freopen 


/* FILENO.C: This program uses fileno to obtain the file handle for 
* some standard C streams. 


“Sf 


#Hinclude <stdio.h> 


void main() 


( 


printf( "The 
printf( "The 
printf( "The 


Output 


The file handle 
The file handle 
The file handle 


file handle for stdin is Zd\n", fileno( stdin ) ); 
file handle for stdout is %d\n", fileno( stdout ) ); 
file handle for stderr is 4d\n", fileno( stderr ) ); 


for stdin is @ 
for stdout is l 
for stderr is 2 


_floodfill, _floodfillw 268 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Fill an area of a display using the current color and fill mask 
#include <graph.h> 


short far _floodfill( short x, short y, short boundary ); 
short far floodfill_w( double wx, double wy, short boundary ); 


x,y Start point 
wx, Wy Start point 
boundary Boundary color of area to be filled 


The functions in the _floodfill family fill an area of the display, using the current color and 
fill mask. The _floodfill routine begins filling at the view-coordinate point (x, y). The 
_floodfill_w routine begins filling at the window-coordinate point (wx, wy). 


If this point lies inside the figure, the interior is filled; if it lies outside the figure, the back- 
ground is filled. The point must be inside or outside the figure to be filled, not on the fig- 
ure boundary itself. Filling occurs in all directions, stopping at the color of boundary. 


The _floodfill functions return a nonzero value if the fill is successful. It returns 0 if the fill 
could not be completed, the starting point lies on the boundary color, or the start point lies 
outside the clipping region. 


O ANS! M@ DOS OF OS/2 O UNIX OO XENIX 


_ellipse functions, _getcolor, _getfillmask, _grstatus, _pie functions, _setfillmask, 
_Setcliprgn, _setcolor 


/* FLOODFIL.C: This program draws a series of nested rectangles in 
* different colors, constantly changing the background color. 


a 


dHinclude <conio.h> 
#Hinclude <stdlib.h> 
dHinclude <graph.h> 
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void main() 
{ 
int loop; 
int xvar, yvar; 


/* find a valid graphics mode */ 
if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 


for( xvar = 163, loop = 9; xvar < 328; loopt+, xvar += 3 ) 
{ 
_setcolor( loop % 16 ); 
yvar = xvar * 5 / 8; 
_rectangle( _GBORDER, 32@-xvar, 2@@-yvar, xvar, yvar ); 
_setcolor( rand() % 16 ); 
_floodfill( 8, 8, loop % 16 ); 
} 
getch(); 
_setvideomode( _DEFAULTMODE ); 
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Description Calculate the floor of a value. 
#include <math.h> 


double floor( double x ); 


long double floorl( long double x ); ve 
x Floating-point value 
Remarks The floor and floor! functions return a floating-point value representing the largest integer 


that is less than or equal to x. 


The floorl function is the 80-bit counterpart, and it uses the 80-bit, 10-byte coprocessor 
form of arguments and return values. See the reference page on the long double functions 
for more details on this data type. 


Return Value These functions return the floating-point result. There is no error return. 


Compatibility floor 
@ ANS| @ DOS W OS/2 HW UNIX” 8 XENIX 


floor! 


O ANS! M@ DOS WM OS/2 DO UNIX OF XENIX 


See Also ceil, fmod 


Example __- 


/* FLOOR.C: This example displays the largest integers less than or equal 
* to the floating-point values 2.8 and -2.8. It then shows the smallest 
* integers greater than or equal to 2.8 and -2.8. 

*/ 


#Hinclude <math.h> 
#Hinclude <stdio.h> 
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void main() 
{ 
double y; 


y = floor( 2.8 ); 
printf( "The floor of 2.8 is %f\n", y ); 
y = floor( -2.8 ); 
printf( "The floor of -2.8 is %f\n", y ); 


y = ceil( 2.8 ); 

printf( “The ceil of 2.8 is %f\n", y ); 
y = ceil( -2.8 ); 

printf( "The ceil of -2.8 is @f\n", y ); 


Output 


The floor of 2.8 is 2.000000 
The floor of -2.8 is -3.99@000 
The ceil. of 2.8 is 3.800000 
The ceil of -2.8 is -2.880000 
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Description Flushes all streams; clears all buffers. 

#include <stdio.h> 

int flushall( void ); 


Remarks The flushall function writes to its associated files the contents of all buffers associated 
with open output streams. All buffers associated with open input streams are cleared of 
their current contents. The next read operation (if there is one) then reads new data from 
the input files into the buffers. 


Buffers are automatically flushed when they are full, when streams are closed, or when a 
program terminates normally without closing streams. 


All streams remain open after the call to flushall. 


Return Value The flushall function returns the number of open streams (input and output). There is no 
error return. 


Compatibility O ANSI @ DOS WM OS/ O UNIX O XENIX 


See Also fflush 


Example 

Le FLUSHALL.C: This program uses flushal] to flush all open buffers. */ 
#Hinclude <stdio.h>: 

ae main() 


int numflushed; 


numflushed = flushall(); 
printf( “There were %d streams flushed\n", numflushed ); 


Output 


There were 3 streams flushed 
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Description Calculates the floating-point remainder. 

#include <math.h> 

double fmod( double x, double y ); 

long double fmodl( long double x, long double y ); 

x,y Floating-point values 
Remarks The fmod and fmodI functions calculate the floating-point remainder f of x / y such that 


Return Value 


Compatibility 


See Also 


Example 


x=i* y+/f, where / is an integer, f has the same sign as x, and the absolute value of f is 
less than the absolute value of y. 


The fmodl function is the 80-bit counterpart; it uses the 80-bit, 10-byte coprocessor form 
of arguments and return values. See the discussion of the long double functions for more 
details on this data type. 


These functions return the floating-point remainder. If y is 0, the function returns 0. 


fmod 
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fmodl] 


O ANS| #@ DOS HM os/72 QO UNIX OO XENIX 


ceil, fabs, floor 


/* FMOD.C: This program displays a floating-point remainder. */ 


dFinclude <math.h> 
dFinclude <stdio.h> 
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void main() 
{ 
double x = =10.0,. y= 3.0, 2; 


z = fmod( x, y ); 

printf( "The remainder of %.2f / %.2f is Zf\n", x, y, z ); 
} 
Output 


The remainder of -18.00 / 3.00 is -1.@90000 
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Description 


Remarks 


fopen 


Opens a file. 
#include <stdio.h> 
FILE *fopen( const char *filename, const char *mode ); 


filename Path name of file 


mode Type of access permitted 


The fopen function opens the file specified by filename. The character string mode speci- 
fies the type of access requested for the file, as follows: 


Type Description 

ad Opens for reading. If the file does not exist or cannot be 
found, the fopen call will fail. 

"Nw" Opens an empty file for writing. If the given file exists, its 
contents are destroyed. 

"qn Opens for writing at the end of the file (appending); creates 
the file first if it doesn’t exist. 

i ee Opens for both reading and writing. (The file must exist.) 

"w+" Opens an empty file for both reading and writing. If the given 


file exists, its contents are destroyed. 


"a+" Opens for reading and appending; creates the file first if it 
doesn’t exist. 


When a file is opened with the "a" or "a+" access type, all write operations occur at the 
end of the file. Although the file pointer can be repositioned using fseek or rewind, the file 
pointer is always moved back to the end of the file before any write operation is carried 
out. Thus, existing data cannot be overwritten. 


When the "r+", "w+", or "a+" access type is specified, both reading and writing are al- 
lowed (the file is said to be open for “update”). However, when you switch between read- 
ing and writing, there must be an intervening fsetpos, fseek, or rewind operation. The 
current position can be specified for the fsetpos or fseek operation, if desired. 


fopen 


Return Value 


Compatibility 


See Also 


Example 
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In addition to the values listed above, one of the following characters can be included in 
mode to specify the translation mode for newline characters: 


Mode Meaning 


t Open in text (translated) mode. In this mode, carriage-return— 
line-feed (CR-LF) combinations are translated into single line 
feeds (LF) on input and LF characters are translated to CR-LF 
combinations on output. Also, CTRL+Z is interpreted as an end- 
of-file character on input. In files opened for reading or for 
reading/writing, fopen checks for a CTRL+Z at the end of the 
file and removes it, if possible. This is done because using the 
fseek and ftell functions to move within a file that ends with a 


CTRL+Z may cause fseek to behave improperly near the end of 
the file. 


b Open in binary (untranslated) mode; the above translations are 
suppressed. 


If t or b is not given in mode, the translation mode is defined by the default-mode variable 
_fmode. If t or b is prefixed to the argument, the function will fail and return NULL. 


See Section 2.7, “Input and Output,” for a discussion of text and binary modes. 


The fopen function retums a pointer to the open file. A null pointer value indicates an 
error. . 


M ANS! @ DOS # OS/2 UNIX’ IB XENIX 


Note that the t option is not part of the ANSI standard for fopen; it is a Microsoft exten- 
sion and should not be used where ANSI portability is desired. 


fclose, fcloseall, fdopen, ferror, fileno, freopen, open, setmode 


/* FOPEN.C: This program opens files named "data" and “data2". It uses 
* fclose to close "data" and fcloseall to close all remaining files. 


*/ 


dHinclude <stdio.h> 
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FILE *stream, *stream2; 


void main() 
{ 
int numclosed; 


/* Open for read (will fail if ‘data’ does not exist) */ 
if( (stream = fopen( “data", "r" )) == NULL ) 

printf( "The file ‘data' was not opened\n"” ); 
else 

printf( “The file ‘data’ was opened\n" ); 


/* Open for write */ 
if( (stream2 = fopen( "“data2", “wt" )).== NULL ) 
printf( "The file ‘data2' was not opened\n" ); 
else 
printf( “The file ‘data2' was opened\n" ); 


/* Close stream */ 
if( fclose( stream ) ) 
printf( "The file ‘data’ was not closed\n" ); 


/* All other files are closed: */ 
numclosed = fcloseall( ); 
printf( "Number of files closed by fcloseall: Zu\n", numclosed ); 


Output 


The file ‘data’ was opened 
The file ‘data2' was opened 
Number of files closed by fcloseall: 1 
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Description . Get or set a far-pointer offset (FP_OFF) or a far-pointer segment (FP_SEG). 
#include <dos.h> 


unsigned FP_OFF( void _far *address ); 
unsigned FP_SEG( void _far *address ); 


address Far pointer to memory address 


Remarks The FP_OFF and FP_SEG macros can be used to set or get the offset and segment, respec- 
tively, of the far pointer at address. 


Return Value The FP_OFF macro returns an offset. The FP_SEG macro returns a segment address. 
Compatibility O ANS! mm DOS WM OS2 UNIX C XENIX 
Example 


/* FP_LSEG.C: This program uses FP_SEG and FP_OFF to obtain 
* the segment and offset of the long pointer p. 
*/ 


#Hinclude <dos.h> 
#Hinclude <malloc.h> 
dHinclude <stdio.h> 


void main() 

{ 
void _far *p; 
unsigned int seg_val; 
unsigned int off_val; 


p = _fmalloc( 180 ); /* Points pointer at something */ 


seg_val = FP_SEG( p ); /* Gets address pointed to */ 
off_val = FPLOFF( p ); 


printf( "Segment is %.4X; Offset is %.4X\n", seg_val, off_val ); 
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Output 


Segment is 00C7; Offset is 8016 
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Description Resets the floating-point package. 
#include <float.h> 
void _fpreset( void ); 


Remarks The _fpreset function reinitializes the floating-point-math package. This function is usu- 
ally used in conjunction with signal, system, or the exec or spawn functions. 


If a program traps floating-point error signals (SIGFPE) with signal, it can safely recover 
from floating-point errors by invoking _fpreset and using longjmp. 


In DOS versions prior to 3.0, a child process executed by exec, spawn, or system may 
affect the floating-point state of the parent process if an 8087 or 80287 coprocessor is 
used. If you are using either coprocessor, the following precautions are recommended: 


m The exec, spawn, and system functions should not be called during the evaluation of a 
floating-point expression. 


m The _fpreset function should be called after these routines if there is a possibility of 
the child process performing any floating-point operations. 


Return Value None. 
Compatibility O ANS! @ DOS mM OS7?2 OO UNIX O XENIX 


See Also exec functions, signal, spawn functions 


Example 


/* FPRESET.C: This program uses signal to set up a routine for handling 


* floating-point errors. 
my 


dFinclude <stdio.h> 
#Finclude <signal.h> 
#Finclude <setjmp.h> 
#Finclude <stdlib.h> 
#Hinclude <float.h> 
#Hinclude <math.h> 
#include <string.h> 
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jmp_buf mark; /* Address for long jump to jump to */ 
int fperr; /* Global error number */ 


void fphandler( int sig, int num ); /* Prototypes */ 
void fpcheck( void ); 


void main() 

{ 
double nl, n2, r; 
int jmpret; 


/* Set up floating point error handler. */ 

if( signal( SIGFPE, fphandler ) == SIG_ERR ) 

{ 
fprintf( stderr, “Couldn't set SIGFPE\n" ); 
abort(); 

} 


/* Save stack environment for return in case of error. First time 
* through, jmpret is @, so true conditional is executed. If an 
* error occurs, jmpret will be set to -1l and false conditional 
* will be executed. 

*/ 

jmpret = setjmp( mark ); 

if( jmpret == @ ) 

{ 

printf( "Test for invalid operation - " ); 
printf( “enter two numbers: " ); 
scanf( "%1f 21f", &nl, &n2 ); 


r=nl /n2; 
/* This won't be reached if error occurs. */ 
printf( "\n\n%4.3g / %4.3g = 424.3g\n", nl, n2, r ); 


r=nl * n2; 
/* This won't be reached if error occurs. */ 
printf ( "\n\n%4.3g * %24.3g = %44.3g\n", nl, n2, r ); 
} 
else 
fpcheck(); 
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/* Handles SIGFPE (floating point error) interrupt. */ 
void fphandler( int sig, int num ) 
{ 
/* Set global for outside check since we don't want to do I/0 in the 
* handler. 
*/ 
fperr = num; 


/* Initialize floating-point package. */ 
_fpreset(); 


/* Restore calling environment and jump back to setjmp. Return -1 
* so that setjmp will return false for conditional test. 
*/ 
longjmp( mark, -1 ); 
} 


void fpcheck() 
{ 
char fpstr[30]; 


switch( fperr ) 
{ 
case FPE_INVALID: 


strepy( fpstr, "Invalid number” ); 
break; 


case FPE_OVERFLOW: 
strepy( fpstr, "Overflow" ); 
break; 


case FPE_UNDERFLOW: 
strepy( fpstr, "Underflow" ); 
break; 


case FPE_ZERODIVIDE: 
strcepy( fpstr, “Divide by zero” ); 
break; 


default: 
strepy( fpstr, "Other floating point error" ); 
break; 
} 
printf( "Error 4d: %s\n", fperr, fpstr ); 


Output 


Test for invalid operation - enter two numbers: 5 @ 
Error 131: Divide by zero 
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Description Prints formatted data to a stream. 
#include <stdio.h> 


int fprintf( FILE *stream, const char *format [ , argument J... )3 


stream Pointer to FILE structure 
format Format-control string 
argument Optional arguments 
Remarks The fprintf function formats and prints a series of characters and values to the output 


stream. Each argument (if any) is converted and output according to the corresponding 
format specification in format. 


The format argument has the same form and function that it does for the printf function; 
see the Remarks section for the printf function for more information on format and 
argument. 


Return Value The fprintf function returns the number of characters printed, or a negative value in the 
case of an output error. 


Compatibility M ANS! M@ DOS MOS MI UNIX. Mf XENIX 
See Also cprintf, fscanf, printf, sprintf 
Example 


/* FPRINTF.C: This program uses fprintf to format various data and 
print them to the file named FPRINTF.OUT. It then displays 
FPRINTF.OUT on the screen using the system function to invoke 
the DOS TYPE command. 


+ + 


wif 


#Hinclude <stdio.h> 
#Hinclude <process.h> 


fprintf 304 


SSS a a a ee DR ee eT EL a 5 a a DT a 
FILE *stream; 


void main() 

{ 
int i = 10; 
double fp = 1.5; 
char s{]) = "this is a string"; 
char c= '\n'; 


stream = fopen( "fprintf.out", "w" ); 
fprintf( stream, "%s%c", s, c ); 
fprintf( stream, "d\n", i ); 
fprintf( stream, "%f\n", fp ); 
fclose( stream ); 

system( "type fprintf.out” ); 


Output 


this is a string 
10 
1.580000 
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Description Write a character to a stream (fputc) or to stdout (fputchar). 

#include <stdio.h> 

int fpute( int c, FILE *stream ); 

int fputchar( int c ); 

Cc Character to be written 

Stream Pointer to FILE structure 
Remarks The fputc function writes the single character c to the output stream at the current posi- 


Return Value 


Compatibility 


See Also 


Example | 


tion. The fputchar function is equivalent to fpute(c, stdout). 


The fputc and fputchar routines are similar to pute and putchar, but are functions rather 
than macros. 


The fputc and fputchar functions return the character written. A return value of EOF indi- 
cates an error. 


fputc 
@ ANS| @ DOS #8 OS/72 UNIX’ Mf XENIX 
fputchar 


O ANS! M@ DOS WM OS/2 O UNIX OO XENIX 


fgetc, fgetchar, putc, putchar 


/* FPUTC.C: This program uses fputc and fputchar to send a character 
* array to stdout. 


*/ 


d#Hinclude <stdio.h> 
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void main() 

{ 
char strptri{] 
char strptr2C] 
char *p; 


"This is a test of fputc!!\n"; 
"This is a test of fputchar!!\n"; 


/* Print line to stream using fputc. */ 
p = strptrl; 
while( (*p != '\@') && fputc( *(ptt+), stdout ) != EOF ) 


/* Print line to stream using fputchar. */ 
p = strptr2; ; 
while( (*p != '\@') && fputchar( *(pt+) ) != EOF ) 


Output 


This is a test of fputc!! 
This is a test of fputchar!! 
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Description Writes a string to a stream. 

#include <stdio.h> 

int fputs( const char *string, FILE “stream ); 

string String to be output 

stream Pointer to FILE structure 
Remarks The fputs function copies string to the output stream at the current position. The terminat- 


Return Value 


Compatibility 


See Also 


Example 


ing null character (?\0’) is not copied. 


The fputs function returns a nonnegative value if it is successful. If an error occurs, it re- 
turns EOF. 


MANS! @ DOS MM OS/2 MW UNIX’ MM XENIX 


fgets, gets, puts 


/* FPUTS.C: This program uses fputs to write a single line to the 
* stdout stream. 


a 


dHinclude <stdio.h> 


void main() 


{ 


fputs( "Hello world from fputs.\n", stdout ); 


) 


Output 


Hello world from fputs. 


fread 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Reads data from a stream. 
#include <stdio.h> 


size_t fread( void *buffer, size_t size, size_t count, FILE *stream ); 


buffer Storage location for data 

size Item size in bytes 

‘count Maximum number of items to be read 
stream Pointer to FILE structure 


The fread function reads up to count items of size bytes from the input stream and stores 
them in buffer. The file pointer associated with stream (if there is one) is increased by the 
number of bytes actually read. 


If the given stream is opened in text mode, carriage-return—line-feed pairs are replaced 
with single line-feed characters. The replacement has no effect on the file pointer or the re- 
turn value. 


The file-pointer position is indeterminate if an error occurs. The value of a partially read 
item cannot be determined. 


The fread function returns the number of full items actually read, which may be less than 
count if an error occurs or if the file end is encountered before reaching count. 


The feof or ferror function should be used to distinguish a read error from an end-of-file 
condition. If size or count is 0, fread returns O and the buffer contents are unchanged. 


@ ANS! @ DOS WM OS/ W UNIX =X XENIX 


fwrite, read 


/* FREAD.C: This program opens a file named FREAD.OUT and writes 25 
* characters to the file. It then tries to open FREAD.OUT and 

* read in 25 characters. If the attempt succeeds, the program 

* displays the number of actual items read. 


ba 
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#include <stdio.h> 


void main() 
{ 
FILE *stream; 
char list[30]; 
int 7, numread, numwritten; 


/* Open file in text mode: */ 
if( (stream = fopen( "fread.out", “wtt" )) != NULL ) 
{ 
for ( 1 =@;3 i < 25; i++ ) 
listCi] = 'z' - i; 
/* Write 25 characters to stream */ 
numwritten = fwrite( list, sizeof( char ), 25, stream ); 
printf( "Wrote 2d items\n", numwritten ); 
fclose( stream ); 
} 
else 
printf( "Problem opening the file\n" ); 


if( (stream = fopen( "fread.out", “r+t" )) != NULL ) 

{ 
/* Attempt to read in 25 characters */ 
numread = fread( list, sizeof( char ), 25, stream ); 
printf( "Number of items read = %d\n", numread ); 
printf( “Contents of buffer = %.25s\n", list ); 
fclose( stream ); °- 

else 
printf( “Was not able to open the file\n" ); 


Output 


Wrote 25 items 
Number of items read = 25 
Contents of buffer = zyxwvutsrqponmlkjihgfedcb 
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Description 


Remarks 


Deallocate a memory block. 


#include <stdlib.h> For ANSI compatibility (free only) 


#include <malloc.h> Required only for function declarations 


void free( void *memblock ); . 
void _bfree(_segment seg, void _based( void ) *memblock ); 
void _ffree( void _far *memblock ); 


void _nfree( void _near *memblock ); 


memblock Allocated memory block 


seg Based-heap segment selector 


The free family of functions deallocates a memory block. The argument memblock points 
to a memory block previously allocated through a call to calloc, malloc, or realloc. The 
number of bytes freed is the number of bytes specified when the block was allocated (or 
reallocated, in the case of realloc). After the call, the freed block is available for 
allocation. 


The seg argument specifies the based heap containing the memory block to be freed by the 
_bfree function. 


Attempting to free an invalid pointer may affect subsequent allocation and cause errors. 
An invalid pointer is one not allocated with the appropriate call. 


The following restrictions apply to use of the free, bfree, ffree, and _nfree functions: 


Blocks allocated with: Should be freed with: 
calloc, malloc, realloc free 

_bcalloc, bmalloc, _brealloc _bfree 

_fcalloc, fmalloc, _frealloc _ffree 

_ncalloc, nmalloc, nrealloc _nfree 


A NULL pointer argument is ignored. 


In large data models (compact-, large-, and huge-model programs), free maps to _ffree. In 
small data models (tiny-, small-, and medium-model programs), free maps to _nfree. 
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The various free functions deallocate a memory block in the segments shown in the list 


below: 

Function Data Segment 

free Depends on data model of program 

_bfree Based heap specified by seg value 

_ffree Far heap (outside default data segment) 

_nfree Near heap (inside default data segment) 
Return Value None. 


Compatibility free 
MANS! @ DOS @ OS/2 WM UNIX Mi XENIX 


_bfree, ffree,_nfree 


O ANS! @ DOS WM OS/22 OF UNIX OF XENIX 


See Also calloc functions, malloc functions, realloc functions 


Example 


/* MALLOC.C: This program allocates memory with malloc, then frees 
* the memory with free. 
* 


dHinclude <stdlib.h> /* Definition of _MAX_PATH */ 
dFinclude <stdio.h> 
dHinclude <malloc.h> 
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void main() 
{ 
char *string; 


/* Allocate space for a path name */ 
string = malloc( _MAX_PATH ); 
if( string == NULL ) 
printf( "Insufficient memory available\n" ); 
‘else 
printf( "Memory space allocated for path name\n" ); 
free( string ); 
printf( "Memory freed\n" ); 


Output 


Memory space allocated for path name 
Memory freed 
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Description 


Remarks 


Return Value 
Compatibility 


See Also 


Example 


_freect 


Returns the amount of memory available for memory allocation. 
#include <malloc.h> Required only for function declarations 
unsigned int _freect( size_t size ); 

size Item size in bytes 


The _freect function tells you how much memory is available for dynamic memory alloca- 
tion in the near heap. It does so by returning the approximate number of times your pro- 
gram can call _nmalloc (or malloc in small data models) to allocate an item size bytes 
long in the near heap (default data segment). 


The _freect function returns the number of calls as an unsigned integer. 
O ANS! @ DOS # OS/72 O UNIX O XENIX 


calloc functions, expand functions, malloc functions, _memavl, _msize functions, 
realloc functions 


/* FREECT.C: This program determines how much free space is available for 
* integers in the default data segment. Then it allocates space for 
* 1,000 integers and checks the space again, using _freect. 


my 


##include <malloc.h> 
#Hinclude <stdio.h> 


void main() 


{ 
int i; 


/* First report on the free space: */ 
printf( "Integers (approximate) available on heap: %u\n\n", 


_freect( sizeof( int ) ) ); 


/* Allocate space for 1800 integers: */ 


for( i = 


@; i < 1000; ++i ) 


malloc( sizeof( int ) ); 
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/* Report again on the free space: */ 

printf( "After allocating space for 1000 integers:\n" ); 

printf( “Integers (approximate) available on heap: Zu\n\n", 
_freect( sizeof( int ) ) ); 


Output 
Integers (approximate) available on heap: 15212 


After allocating space for 1088 integers: 
Integers (approximate) available on heap: 14084 
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Description Reassigns a file pointer. 

#include <stdio.h> 

FILE *freopen( const char *filename, const char *mode, FILE *stream ); 

filename Path name of new file 

mode Type of access permitted 

stream Pointer to FILE structure 
Remarks The freopen function closes the file currently associated with stream and reassigns stream 


to the file specified by filename. The freopen function is typically used to redirect the pre- 
opened files stdin, stdout, and stderr to files specified by the user. The new file associ- 
ated with stream is opened with mode, which is a character string specifying the type of 
access requested for the file, as follows: 


Type Description 


Opens for reading. If the file does not exist or cannot be 
found, the freopen call fails. 


"w' Opens an empty file for writing. If the given file exists, its 
contents are destroyed. 

Ta" Opens for writing at the end of the file (appending); creates 
the file first if it does not exist. 

py Opens for both reading and writing. (The file must exist.) 

"wt! Opens an empty file for both reading and writing. If the given 
file exists, its contents are destroyed. 

"a+" Opens for reading and appending; creates the file first if it 


does not exist. 


Use the "w" and "w+" types with care, as they can destroy existing files. 


When a file is opened with the "a" or "a+" access type, all write operations take place at 
the end of the file. Although the file pointer can be repositioned using fseek or rewind, the 
file pointer is always moved back to the énd of the file before any write operation is car- 
ried out. Thus, existing data cannot be overwritten. 


freopen 
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Return Value 


Compatibility 


See Also 


Example 


When the "r+", "w+", or "a+" access type is specified, both reading and writing are al- 
lowed (the file is said to be open for “update”). However, when you switch between read- 
ing and writing, there must be an intervening fsetpos, fseek, or rewind operation. The 
current position can be specified for the fsetpos or fseek operation, if desired. 


In addition to the values listed above, one of the following characters may be included in 
the mode string to specify the translation mode for newlines. 


Mode Meaning 


t Open in text (translated) mode; carriage-return—line-feed 
(CR-LF) combinations are translated into single line-feed 
(LF) characters on input; LF characters are translated to CR- 
LF combinations on output. Also, CTRL+Z is interpreted as an 
end-of-file character on input. In files opened for reading, or 
writing and reading, the run-time library checks for a CTRL+Z 
at the end of the file and removes it, if possible. This is done 
because using the fseek and ftell functions to move within a 
file may cause fseek to behave improperly near the end of the 
file. 


b . Open in binary (untranslated) mode; the above translations are 
suppressed. 


If t or b is not given in the mode string, the translation mode is defined by the default 
mode variable _fmode. 


See Section 2.7, “Input and Output,” for a discussion of text and binary modes. 


The freopen function returns a pointer to the newly opened file. If an error occurs, the orig- 
inal file is closed and the function returns a NULL pointer value. 


BANS! M@ DOS #8 OS/ MW UNIX' W@W XENIX 


The t option is not part of the ANSI standard for freopen; it is a Microsoft extension that 
should not be used where ANSI portability is desired. 


fclose, fcloseall, fdopen, fileno, fopen, open, setmode 


/* FREOPEN.C: This program reassigns stdaux to the file 
* named FREOPEN.OUT and writes a line to that file. 


a 
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#Hinclude <stdio.h> 
dHinclude <stdlib.h> 


FILE *stream; 


void main() 


( 


/* Reassign “stdaux" to “freopen.out": */ 
stream = freopen( "freopen.out", "w", stdaux ); 


if( stream == NULL ) 
fprintf( stdout, “error on freopen\n" ); 
else 
{ 
fprintf( stream, “This will go to the file ‘'freopen.out'\n" ); 
fprintf( stdout, “successfully reassigned\n" ); 
fclose( stream ); 
} 
system( “type freopen.out" ); 


Output 


successfully reassigned 
This will go to the file 'freopen.out' 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Get the mantissa and exponent of a floating-point number. 
#include <math.h> 


double frexp( double x, int *expptr ); 
long double frexpl( long double x, int *expptr ); 


x Floating-point value 


expptr Pointer to stored integer exponent 
The frexp and frexpl functions break down the floating-point value (x) into a mantissa (mm) 
and an exponent (7), such that the absolute value of m is greater than or equal to 0.5 and 


less than 1.0, and x = m*2", The integer exponent n is stored at the location pointed to by 
expptr. 


The frexpl function is the 80-bit counterpart and uses an 80- bit, 10-byte coprocessor form 
of arguments and return values. See the reference page on the long double functions for 
more details on this data type. 


These functions return the mantissa. If x is 0, the function returns 0 for both the mantissa 
and the exponent. There is no error return. 
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frexpl 
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Idexp functions, modf 


/* FREXP.C: This program calculates frexp( 16.4, &n ), then displays y 


* and n. 
* | 


#Hinclude <math.h> 
#Finclude <stdio.h> 
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void main() 

{ 
double x, y; 
int n; 


x = 16.4; 
= frexp( x, &n ); 
Sranent "frexp( 2f, &n ) = 4f, n = d\n", x, y, n ); 
} 
Output 


frexp( 16.490000, &n ) = 8.512580, n = 5 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Reads formatted data from a stream. 
#include <stdio.h> 


int fscanf( FILE *stream, const char *format [, argument Jl... ) 


stream Pointer to FILE structure 
format Format-control string 
argument Optional arguments 


The fscanf function reads data from the current position of stream into the locations given 
by argument (if any). Each argument must be a pointer to a variable with a type that corre- 
sponds to a type specifier in format. The format controls the interpretation of the input 
fields and has the same form and function as the format argument for the scanf function; 
see scanf for a description of format. 


The fscanf function returns the number of fields that were successfully converted and as- 
signed. The return value does not include fields that were read but not assigned. 


The return value is EOF for an error or end-of-file on stream before the first conversion. A 
return value of 0 means that no fields were assigned. 
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cscanf, fprintf, scanf, sscanf 


/* FSCANF.C: This program writes formatted data to a file. It 


=] 


* then uses fscanf to read the various data back from the file. 


#Hinclude <stdio.h> 
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FILE *stream; 


void main() 

{ 
long 1; 
float fp; 
char s[81]; 
char c; 
int result; 


stream = fopen( “fscanf.out", "wt" ); 
if( stream == NULL ) 
printf( "The file fscanf.out was not opened\n" ); 
else 
( 
fprintf( stream, "%s 21d 4f%c", “a-string", 65000, 3.14159, ‘x' ); 


/* Set pointer to beginning of file: */ 
fseek( stream, OL, SEEK_SET ); 


/* Read data back from file: */ 
fscanf( stream, "4s", s ); 
fscanf( stream, "41d", &1 ); 
fscanf( stream, "%f", &fp ); 
fscanf( stream, "%c", &c ); 


/* Output data read: */ 
printf( "Ss\n", s ); 
printf( "%ld\n", 1 ); 
printf( "%f\n", fp ); 
printf( “&c\n", c ); 


fclose( stream ); 


Output 


a-string 
65808 
3.141598 
Xx 


fseek 


322 


Description 


Rematks 


Moves the file pointer to a specified location. 
#include <stdio.h> 


int fseek( FILE *stream, long offset, int origin ); 


Stream Pointer to FILE structure 
offset Number of bytes from origin 
origin Initial position 


The fseek function moves the file pointer (if any) associated with stream to a new location 
that is offset bytes from origin. The next operation on the stream takes place at the new lo- 
cation. On a stream open for update, the next operation can be either a read or a write. 


The argument origin must be one of the following constants defined in STDIO.H: 


Origin Definition 

SEEK_CUR Current position of file pointer 
SEEK_END End of file 

SEEK_SET Beginning of file 


The fseek function can be used to reposition the pointer anywhere in a file. The pointer 
can also be positioned beyond the end of the file. However, an attempt to position the 
pointer in front of the beginning of the file causes an error. 


The fseek function clears the end-of-file indicator and negates the effect of any prior 
ungetc calls against stream. 


When a file is opened for appending data, the current file position is determined by the last 
I/O operation, not by where the next write would occur. If no I/O operation has yet oc- 
curred on a file opened for appending, the file position is the start of the file. 


For streams opened in text mode, fseek has limited use because carriage-return—line-feed 
translations can cause fseek to produce unexpected results. The only fseek operations 
guaranteed to work on streams opened in text mode are the following: 


@ Seeking with an offset of 0 relative to any of the origin values 


m@ Seeking from the beginning of the file with an offset value returned from a call to ftell 
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Return Value If successful, fseek returns 0. Otherwise, it returns a nonzero value. On devices incapable 
of seeking, the return value is undefined. 


Compatibility @ ANS! @ DOS HF OS/2 UNIX’ Wf XENIX 
See Also ftell, Iseek, rewind 
Example 


/* FSEEK.C: This program opens the file FSEEK.OUT and 
* moves the pointer to the file's beginning. 
*/ 


#Hinclude <stdio.h> 


void main() 

( 
FILE *stream; 
char line({81]; 
int result; 


stream = fopen( "fseek.out", “wt" ); 
if( stream == NULL ) 
printf( "The file fseek.out was not opened\n" ); 
else 
{ 
fprintf( stream, “The fseek begins here: " 
"This is the file ‘fseek.out’.\n" ); 
result = fseek( stream, 23L, SEEK_SET); 
if( result ) 
perror( "Fseek failed" ); 
else 
{ 
printf( “File pointer is set to middle of first line.\n" ); 
fgets( line, 88, stream ); 
printf( "%s", line ); 
) 
fclose( stream ); 


Output 


File pointer is set to middle of first line. 
This is the file 'fseek.out’. 
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Description Sets the stream-position indicator. 
#include <stdio.h> 


int fsetpos( FILE *stream, const fpos_t *pos ) ; 


stream . Target stream 
pos 2 Position-indicator storage 
Remarks The fsetpos function sets the file-position indicator for stream to the value of pos, which is 


obtained in a prior call to fgetpos against stream. 


The function clears the end-of-file indicator and undoes any effects of the ungetc function 
on stream. After calling fsetpos, the next operation on stream may be either input or 
output. 


Return Value If successful, the fsetpos function returns 0. On failure, the function returns a nonzero 
value and sets errno to one of the following manifest constants (defined in ERRNO.H): 


_ Constant Meaning 
EBADF The object that stream points to is not a valid file handle, or 


the file is not accessible. 


EINVAL An invalid stream value was passed. 
Compatibility MANS! @ DOS moOS?2 OF UNIX OC XENIX 


See Also fgetpos 


Example 

/* FGETPOS.C: This program opens a file and reads bytes at several 
* different locations. 

* / : 


#Hinclude <stdio.h> 
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void main() 


{ 


FILE *stream; 
fpos_t pos; 

int val; 

char buffer[20]; 


if( (stream = fopen( “fgetpos.c", “rb” )) == NULL ) 
printf( "Trouble opening file\n" ); 
else 
{ 
/* Read some data and then check the position. */ 
fread( buffer, sizeof( char ), 10, stream ); 
if( fgetpos( stream, &pos ) != @ ) 
perror( “fgetpos error" ); 
else 
{ 
fread( buffer, sizeof( char ), 10, stream ); 
printf( "10 bytes at byte 41d: %.1@s\n", pos, buffer ); 
} 


/* Set a new position and read more data. */ 
pos = 140; 
if( fsetpos( stream, &pos ) !=@ ) 

perror( “fsetpos error” ); 


fread( buffer, sizeof( char ), 10, stream ); 
printf( "1@ bytes at byte 41d: %.10s\n", pos, buffer ); 


fclose( stream ); 


Output 


19 bytes at byte 1@: .C: This p 
1@ bytes at byte 140: FILE * 
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Description Opens a stream with file sharing. 
#include <stdio.h> 
#include <share.h> shflag constants 


FILE *_fsopen( const char *filename, const char *mode, int shflag ); 


filename File name to open 
mode Type of access permitted 
shflag Type of sharing allowed 

Remarks The._fsopen function opens the file specified by filename as a stream and prepares the 
file for subsequent shared reading or writing, as defined by the mode and shflag 
arguments. 


The character string mode specifies the type of access requested for the file, as follows: 


Type Description 
a Opens for reading. If the file does not exist or cannot be 
found, the _fsopen call will fail. 


"yw" Opens an empty file for writing. If the given file exists, its 
contents are destroyed. 

ee Opens for writing at the end of the file (appending); creates 
the file first if it does not exist. 

a coe Opens for both reading and writing. (The file must exist.) 

i Opens an empty file for both reading and writing. If the given’ 


file exists, its contents are destroyed. 


"a+" Opens for reading and appending; creates the file first if it 
does not exist. 


Use the "w" and "w+" types with care, as they can destroy existing files. 


When a file is opened with the "a" or "a+" access type, all write operations occur at the 
end of the file. Although the file pointer can be repositioned using fseek or rewind, the file 
pointer is always moved back to the end of the file before any write operation is carried 
out. Thus, existing data cannot be overwritten. 
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When the "r+", "w+", or "a+" access type is specified, both reading and writing are al- 
lowed (the file is said to be open for “update”). However, when switching between reading 
and writing, there must be an intervening fsetpos, fseek, or rewind operation. The current 
position can be specified for the fsetpos or fseek operation, if desired. 


In addition to the values listed above, one of the following characters can be included in 
mode to specify the translation mode for newlines: 


Mode — Meaning 


t Open in text (translated) mode. In this mode, carriage-return— 
line-feed (CR-LF) combinations are translated into single line 
feeds (LF) on input and LF characters are translated to CR-LF 
combinations on output. Also, CTRL+Z is interpreted as an end- 
of-file character on input. In files opened for reading or read- 
ing/writing, fsopen checks for a CTRL+Z at the end of the file 
and removes it, if possible. This is done because using the 
fseek and ftell functions to move within a file that ends with a 
CTRL+Z may cause fseek to behave improperly near the end of 
the file. 


b Open in binary (untranslated) mode; the above translations are 
suppressed. 


If t or b is not given in mode, the translation mode is defined by the default-mode variable 
_fmode. If t or b is prefixed to the argument, the function will fail and will return NULL. 


See Section 2.7, “Input and Output,” for a discussion of text and binary modes. 


The argument shflag is a constant expression consisting of one of the following manifest 
constants, defined in SHARE.H. If SHARE.COM —or SHARE.EXE for some versions of 
DOS— is not installed, DOS ignores the sharing mode. (See your system documentation 
for detailed information about sharing modes.) 


Constant Meaning 

SH_COMPAT Sets compatibility mode (not available in OS/2) 
SH_DENYNO Permits read and write access 

SH_DENYRD Denies read access to file 

SH_DENYRW Denies read and write access to file. 
SH_DENYWR Denies write access to file 


The _fsopen function should be used only under OS/2 and DOS versions 3.0 and later. 
Under earlier versions of DOS, the shflag argument is ignored. _ 
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Return Value The _fsopen function returns a pointer to the stream. A NULL pointer value indicates an 
error. 

Compatibility O ANS! @ DOS moOS/72 CO UNIX Oj XENI 

See Also fclose, fcloseall, fdopen, ferror, fileno, fopen, freopen, open, setmode, sopen 

Example 


/* FSOPEN.C: This program opens files named "data" and "data2". It uses 
* fclose to close "data" and fcloseall to close all remaining files. 
*/ 


#include <stdio.h> 
dHinclude <share.h> 


FILE *stream; 


void main() 
{ 
FILE *stream; 


/* Open output file for writing. Using _fsopen allows us to ensure 
* that no one else writes to the file while we are writing to it. 
*/ 

if( (stream = _fsopen( “outfile", "wt", SH _DENYWR )) != NULL ) 

{ 

fprintf( stream, "No one else in the network can write " 
"to this file until we are done.\n” ); 
fclose( stream ); 

} 

/* Now others can write to the file while we read it. */ 

system( "type outfile" ); 


Output 


No one else in the network can write to this file until we are done. 
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Description Gets information about an open file. 
#include <sys\types.h> 
#include <sys\stat.h> 
int fstat( int handle, struct stat *buffer ); 
handle Handle of open file 
buffer . Pointer to structure to store results 
- Remarks The fstat function obtains information about the open file associated with handle and 


stores it in the structure pointed to by buffer. The structure, whose type stat is defined in 
SYS\STAT.H, contains the following fields: 


Field Value 

st_atime Time of last modification of file (same as st_mtime and 
st_ctime). 

st_ctime Time of last modification of file (same as st_atime and 


st_mtime). 


st_dev Either the drive number of the disk containing the file, or 
handle in the case of a device (same as st_rdey). 


st_mode Bit mask for file-mode information. The S_IFCHR bit is set if 
handle refers to a device. The S_IFREG bit is set if handle re- 
fers to an ordinary file. The read/write bits are set according to 
the file’s permission mode. (S_IFCHR and other constants are 


defined in SYS\ STAT.H.) 

st_mtime Time of last modification of file (same as st_atime and 
st_ctime). 

st_nlink Always 1. 

st_rdev Either the drive number of the disk containing the file, or 


handle in the case of a device (same as st_dev). 


-St_size . Size of the file in bytes. 


If handle refers to a device, the size and time fields in the stat structure are not 
meaningful. 
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Return Value The fstat function returns the value 0 if the file-status information is obtained. A return 


value of —1 indicates an error; in this case, errno is set to EBADF, indicating an invalid file 
handle. 


Compatibility O ANS! @ DOS # OS/2 WM UNIX MF XENIX 


See Also 


Example 


/* FSTAT 
* named 
*/ 


#Hinclude. 


#Hinclude 
#Hinclude 
#Hinclude 
#include 
#Hinclude 
#Hinclude 
#Hinclude 


In OS/2, the st_dev field does not contain meaningful information. In fact, it is set to zero. 
OS/2 provides no way to recover the host drive from just the open file handle. 


access, chmod, filelength, stat 


.C: This program uses fstat to report the size of a file 
FSTAT.OUT. 


<io.h> 

<fentl .h> 
<time.h> 
<sys\types.h> 
<sys\stat.h> 
<stdio.h> 
<stdlib.h> 
<string.h> 


void main() 


{ 


struct stat buf; 


int fh, result; 
char buffer[] = “A line to output"; 


if( (fh = open( “fstat.out", O_CREAT | OLWRONLY | O_TRUNC )) == -1 ) 
exit( 1 ); a: 
write( fh, buffer, strlen( buffer ) ); 


/* Get data associated with "fh": */ 


result = fstat( fh, &buf ); 
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/* Check if statistics are valid: */ 
if( result !=@ ) 
printf( “Bad file handle\n" ); 
else 
{ 
printf( "File size : S1d\n", buf.st_size ); 
printf( "Drive number : %d\n", buf.st_dev ); 
printf( "Time modified : %s", ctime( &buf.st_atime ) ); 
} 
close( fh ); 


Output 
File size : 16 
Drive number : @ 


Time modified : Thu Jun 15 21:38:46 1989 
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Description 


Remarks 


Return Value 


Gets the current position of a file pointer. 
#include <stdio.h> 

long ftell( FILE *stream ); 

stream Target FILE structure 


The ftell function gets the current position of the file pointer (if any) associated with 
stream. The position is expressed as an offset relative to the beginning of the stream. 


Note that when a file is opened for appending data, the current file position is determined 
by the last I/O operation, not by where the next write would occur. For example, if a file is 
opened for an append and the last operation was a read, the file position is the point where 
the next read operation would start, not where the next write would start. (When a file is 
opened for appending, the file position is moved to end-of-file before any write operation.) 
If no I/O operation has yet occurred on a file opened for appending, the file position is the 
beginning of the file. 


The ftell function returns the current file position. The value returned by ftell may not re- 
flect the physical byte offset for streams opened in text mode, since text mode causes 
catriage-return—line-feed translation. Use ftell in conjunction with the fseek function to re- 
turn to file locations correctly. On error, the function returns —1L and errno is set to one of 
the following constants, defined in ERRNO.H: 


Constant Description 


EBADF Bad file number. The stream argument is not a valid file- 
handle value or does not refer to an open file. 


EINVAL Invalid argument. An invalid stream argument was passed to 
. the function. 


On devices incapable of seeking (such as terminals and printers), or when stream does not 
refer to an open file, the return value is undefined. 
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Compatibility M@ ANS! @ DOS HH OS/2 MW UNIX WB XENIX 
See Also fgetpos, fseek, Iseek, tell 
Example 


/* FTELL.C: This program opens a file named FTELL.C for reading and 
* tries to read 100 characters. It then uses ftell to determine the 
* position of the file pointer and displays this position. 

*/ 


dHinclude <stdio.h> 
FILE *stream; 


void main() 

{ 
long position; 
char list{10@]; 


if( (stream = fopen( "fteli.c", “rb” )) != NULL ) 
{ 

/* Move the pointer by reading data: */ 

fread( list, sizeof( char ), 100, stream ); 


/* Get position after read: */ 
position = ftell( stream ); 


printf( “Position after trying to read 100 bytes: %1d\n", position ); 
fclose( stream ); 


Output 


Position after trying to read 100 bytes: 180 
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Description 


Remarks | 


Return Value 


Compatibility 


Gets the current time. 


#include <sys\types.h> 
#include <sys\timeb.h> 


void ftime( struct timeb *timeptr ); 
timeptr Pointer to structure defined in SYS\TIMEB.H 


The ftime function gets the current time and stores it in the structure pointed to by timeptr. 
The timeb structure is defined in SYS\TIMEB.H. It contains four fields (dstflag, millitm, 
time, and timezone), which have the following values: 


Field Value 


dstflag Nonzero if daylight saving time is currently in effect for the 
local time zone. (See tzset for an explanation of how daylight 
saving time is determined.) 


millitm Fraction of a second in milliseconds. The last digit is always 0 
since millitm is incremented to the nearest one-hundredth of a 
second. 

time Time in seconds since 00:00:00 Greenwich mean time, 


January 1, 1970. 


timezone Difference in minutes, moving westward, between Greenwich 
mean time and local time. The value of timezone is set from 
the value of the global variable timezone (see tzset). 


The ftime function gives values to the fields in the structure pointed to by timeptr. It does 
not return a value. 
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See Also asctime, ctime, gmtime, localtime, time, tzset 


Example 


/* FTIME.C: This program uses ftime to obtain the current time 
* and then stores this time in timebuffer. 

~} 

#Hinclude <stdio.h> 

#Hinclude <sys\timeb.h> 

#Finclude <time.h> 


void main() 
{ 


struct timeb timebuffer; 
char *timeline; 


ftime( &timebuffer )-; 
timeline = ctime( & ( timebuffer.time ) ); 


printf( "The time is %.19s.%hu %s", 
timeline, timebuffer.millitm, &timeline[20] ); 


Output 


The time is Thu Jun 15 21:40:34.870 1989 
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Description Makes an absolute path name from a relative path name. 
#include <stdlib.h> 


char * fullpath( char “buffer, const char *pathname, size_t maxlen ); 


buffer Full path-name buffer 
pathname - Relative path name 
maxlen Length of the buffer pointed to by buffer 

Remarks © The _fullpath routine converts the partial path stored in pathname to a fully qualified path 
that is stored in buffer. Unlike _makepath, the _fullpath routine can be used with .\ and ..\ 
in the path. 


If the length of the fully qualified path is greater than the value of maxlen, then NULL is 
returned; otherwise, the address of buffer is returned. 


If the buffer is NULL, _fullpath will allocate a buffer of MAX_PATH size and the 
maxlen argument is ignored. 


If the pathname argument specifies a disk drive, the current directory of this drive is com- 
bined with the path. If the drive is not valid, fullpath returns NULL. 


Return Value The _fullpath function returns a pointer to the buffer containing the absolute path 
(buffer). If there is an error, fullpath returns NULL. 


Compatibility O ANS!| @ DOS HM OSf2 OO UNIX OO XENIX 
See Also getcwd, getdcwd, _makepath, _splitpath 
ETN x a a a es 


/* FULLPATH.C: This program demonstrates how _fullpath creates a full 
* path from a partial path. 
*/ 


dHinclude <stdio.h> 
#Finclude <conio.h> 
d#Finclude <stdlib.h> 
#Hinclude <direct.h> 
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char full{_MAX_PATH], partC_MAX_PATH]; 


void main() 
{ 
while( 1 ) 
{ 
printf( "Enter partial path or ENTER to quit: “ ); 
gets( part ); 
if( part(@] == @ ) 
break; 


if( _fullpath( full, part, _MAX_PATH ) != NULL ) 
printf( "Full path is: %s\n", full ); 

else 
printf( “Invalid path\n" ); 


Output 


Enter partial path or ENTER to quit: 

Full path is: C:\ 

Enter partial path or ENTER to quit: ..\include 
Full path is: C:\include 

Enter partial path or ENTER to quit: p: 

Full path is: P:\ 

Enter partial path or ENTER to quit: fullpath.c 
Full path is: C:\LIBREF\fullpath.c 

Enter partial path or ENTER to quit: 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Writes data to a stream. 
#include <stdio.h> 


size_t fwrite( const void *buffer, size_t size, size_t count, FILE “stream ); 


buffer Pointer to data to be written 

size | Item size in bytes | 

count Maximum number of items to be written 
stream Pointer to FILE structure 


The fwrite function writes up to count items, of length size each, from buffer to the output 
stream. The file pointer associated with stream (if there is one) is incremented by the num- 
ber of bytes actually written. 


If stream is opened in text mode, each carriage return is replaced with a carriage-return— 
line-feed pair. The replacement has no effect on the return value. 


The fwrite function returns the number of full items actually written, which may be less 
than count if an error occurs. Also, if an error occurs, the file-position indicator cannot be 
determined. 
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fread, write 


/* FREAD.C: This program opens a file named FREAD.OUT and writes 25 


+ % 


ee 


characters to the file. It then tries to open FREAD.OUT and 
read in 25 characters. If the attempt succeeds, the program 
displays the number of actual items read. 


#Hinclude <stdio.h> 
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void main() 
( 
FILE *stream; 
char list(3@]; 
int i, numread, numwritten; 


/* Open file in text mode: */ 
if( (stream = fopen( “fread.out", "wtt" )) != NULL ) 
{ 
for ( i = @; i < 25; i++ ) 
listlt] = <2* = 43 
/* Write 25 characters to stream */ 
numwritten = fwrite( list, sizeof( char ), 25, stream ); 
printf( "Wrote %d items\n", numwritten ); 
fclose( stream ); 
} 
else 
printf( “Problem opening the file\n" ); 


if( (stream = fopen( "fread.out", “r+t" )) != NULL ) 

{ 
/* Attempt to read in 25 characters */ 
numread = fread( list, sizeof( char ), 25, stream ); 
printf( "Number of items read = %d\n", numread ); 
printf( "Contents of buffer = %.25s\n", list ); 
fclose( stream ); 

} 

else 
printf( "Was not able to open the file\n" ); 


Output ’ 


Wrote 25 items 
Number of items read = 25 
Contents of buffer = zyxwvutsrqponmlkjihgfedcb 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


Converts a floating-point value to a string, which it stores in a buffer. 
#include <stdlib.h> Required only for function declarations 


char *gcvt( double value, int digits, char *buffer ); 


value Value to be converted 
digits Number of significant digits stored 
buffer Storage location for result 


The gevt function converts a floating-point value to a character string and stores the string 
in buffer. The buffer should be large enough to accommodate the converted value plus a 
terminating null character (’\0’), which is appended automatically. There is no provision 
for overflow. 


The gevt function attempts to produce digits significant digits in decimal format. If this is 
not possible, it produces digits significant digits in exponential format. Trailing zeros may 
be suppressed in the conversion. 


The gevt function returns a pointer to the string of digits. There is no error return. 
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atof, atoi, atol, ecvt, fevt 


/* GCVT.C: This program converts -3.1415e5 to its string representation. */ 


dHinclude <stdlib.h> 
dtinclude <stdio.h> 
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void main() 
( 
char buffer[50]; 
double source = -3.1415e5; 


gcvt( source, 7, buffer ); 


printf( “source: @f buffer: ‘'&%s'\n", source, buffer ); 


Output 


source: -314150.000000 buffer: '-314150.' 
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Description Gets the current active page number. 
#include <graph.h> 


short far getactivepage( void ); 


Remarks The _getactivepage function returns the number of the current active page. 


Return Value The function returns the number of the current active page. All hardware combinations sup- 
port at least one page (page number 0). In OS/2, only page 0 is valid. 


Compatibility O ANS! @ DOS OF OS/72 O UNIX OO XENIX 


See Also _getactivepage, getvideoconfig, getvisualpage, _grstatus, _setactivepage, 


_Setvideomode, _setvisualpage 


Example 

/* PAGE.C illustrates video page functions including: 

* _getactivepage _getvisualpage _setactivepage _setvisualpage 
*/ 


fHinclude <conio.h> 
fHinclude <graph.h> 
#Hinclude <stdlib.h> 


void main() 

{ 
short oldvpage, oldapage, page, row, col, line; 
struct videoconfig vc; 
char buf[8@]; 


_getvideoconfig( &vc ); 
if( vce.numvideopages < 4 ) 


exit( 1 ); /* Fail for OS/2 or monochrome. */ 
Oldapage = _getactivepage(); 
oldvpage = _getvisualpage(); 


_displaycursor( _GCURSOROFF ); 
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/* Draw arrows in different place on each page. */ 
for( page = 1; page < 4; paget+ ) 
{ 


_setactivepage( page ); 
_settextposition( 12, 16 * page ); 
_Outtext( ">>>>>>>>"_); 

} 


while( !kbhit() ) 
/* Cycle through pages 1 to 3 to show moving image. */ 
for( page = 1; page < 4; paget+ ) 
_setvisualpage( page ); 
getch(); 


/* Restore original page (normally 9) to restore screen. */ 
_setactivepage( oldapage ); 
_setvisualpage( oldvpage ); 
_displaycursor( _GCURSORON ); 
} 
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Description Determines the endpoints in viewport coordinates of the most recently drawn arc or pie. 
#include <graph.h> 


short far _getarcinfo( struct xycoord _far *start, struct xycoord _far *end, 
struct xycoord _far *fillpoint ); 


Start Starting point of arc 
end Ending point of arc 
fillpoint Point at which pie fill will begin 
Remarks The _getarcinfo function determines the endpoints in viewport coordinates of the most re- 


cently drawn arc or pie. 


If successful, the _getarcinfo function updates the start and end xycoord structures to con- 
tain the endpoints (in viewport coordinates) of the arc drawn by the most recent call to one 
of the _arc or _pie functions. 


In addition, fillpoint specifies a point from which a pie can be filled. This is useful for 
filling a pie in a color different from the border color. After a call to _getarcinfo, change 
colors using the _setcolor function. Use the color, along with the coordinates in fillpoint, 
as arguments for the floodfill function. 


Return Value The _getarcinfo function returns a nonzero value if successful. If neither the _are nor the 
_pie function has been successfully called since the last time the screen was cleared or a 
new graphics mode or viewport was selected, the _getarcinfo function returns 0. 


Compatibility O ANS! @ DOS OQ oOSs/f OO UNIX OC XENIX 
See Also _arc functions, _floodfill, _getvideoconfig, _grstatus, _ pie functions 


Example See the example for _are. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets the current background color. 
#include <graph.h> 
long _far _getbkcolor( void ); 


The _getbkcolor function returns the current background color. The default is 0. 


In a color text mode such as_TEXTC80, setbkcolor accepts, and _getbkcolor returns, a 
color index. For example, _setbkcolor(2L) sets the background color to color index 2. The 
actual color displayed depends on the palette mapping for color index 2. The default for 
color index 2 is green in a color text mode. 


In a color graphics mode such as_ERESCOLOR, _setbkcolor accepts and _getbkcolor re- 
turns a color value (as used in_remappalette). The value for the simplest background 
colors is given by the manifest constants defined in the GRAPH.H include file. For ex- 
ample, setbkcolor( GREEN) sets the background color in a graphics mode to green. 
These manifest constants are provided as a convenience in defining and manipulating the 
most common colors. In general, the actual range of colors is much greater. 


In most cases, whenever an argument is long, it refers to a color value, and whenever it is 
short, it refers to a color index. The two exceptions are_setbkcolor and _getbkcolor, de- 
scribed above. For a more complete discussion of colors, see_remappalette. 


The function returns the current background color value. There is no error return. 
O ANS! @ DOS MW OS/72 O UNIX OF XENIX 
_remappalette, _setbkcolor 


See the example for _getcolor. 
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Description Reads a character from a stream (getc), or gets a character from stdin (getchar). 
#include <stdio.h> 


int getc( FILE *stream ); 
int getchar( void ); 


stream Current stream 


Remarks The getc macro reads a single character from the stream position and increments the as- 
sociated file pointer (if there is one) to point to the next character. The getchar macro is 
identical to getc(stdin). 


The getc and getchar routines are similar to fgetc and fgetchar, pee Vein but are mac- 
ros rather than functions. 


Return Value The getc and getchar macros return the character read. A return value of EOF indicates an 
error or end-of-file condition. Use ferror or feof to determine whether an error or end-of- 
file occurred. 


Compatibility getc 
MANS! @ DOS #8 OS/2 MW UNIX’ WB XENIX 
getchar 


@ ANS! M@ DOS HH OS/2 MW UNIX =f XENIX 


See Also fgetc, fgetchar, getch, getche, putc, putchar, ungetc 


Example 


/* GETC.C: This program uses getchar to read a single line of input 
* from stdin, places this input in buffer, then terminates the 

* string before printing it to the screen. 

*/ : 


dHinclude <stdio.h> 
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void main() 

{ 
char buffer[81]; 
int i, ch; 


printf( “Enter a line: " ); 


/* Read in single line from “stdin": */ 


for( i = @; (i < 88) && ((ch = getchar()) != EOF) && (ch != ‘\n'); it+ ) 
bufferCli] = ch; 


/* Terminate string with null character: */ 
bufferLi] = '\Q'; 
printf( "%s\n", buffer ); 

} 


Output 


Enter a line: This is a line of text. 
This is a line of text. 


getch, getche 348 


Description 


Remarks 


Return Value 
Compatibility 


See Also 


Example 


Get a character from the console without echo (getch) or with echo (getche). 
#include <conio.h> Required only for function declarations 


int getch( void ); 
int getche( void ); 
The getch function reads a single character from the console without echoing. The getche 


function reads a single character from the console and echoes the character read. Neither 
function can be used to read CTRL+C. 


When reading a function key or cursor-moving key, the getch and getche functions must 
be called twice; the first call returns 0 or OxEO, and the second call returns the actual key 
code. 


The getch function returns the character read. There is no error return. 
O ANS! @ DOS WM OS/7 O UNIX QO XENIX 


cgets, getchar, ungetch 


/* GETCH.C: This program reads characters from the keyboard until it 


* receives a 


kf 


'Y' or 


y. 


#Finclude <conio.h> 
#Hinclude <ctype.h> 
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void main() 
{ 
int ch; 


cputs( “Type ‘Y' when finished typing keys: " ); 
do 
{ 
ch = getch(); 
ch = toupper( ch ); 
} while( ch != 'Y' ); 


putch( ch ); 


putch( '\r' ); /* Carriage return */ 
putch( ‘\n' ); /* Line feed x] 
} 
Output 


Type 'Y' when finished typing keys: Y 
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Description Gets the current color. 

#include <graph.h> 

short far _getcolor( void ); 


Remarks The _getcolor function returns the current graphics color index. The default is the highest 
legal value of the current palette. 


Return Value The _getcolor function returns the current color index. 
Compatibility O ANS! @ DOS QO OS7?2 O UNIX OO XENIX 
See Also _Setcolor 

Example 

/* QUTTXT.C: This example illustrates text output functions: 

* _gettextcolor _getbkcolor -_gettextposition -_outtext 
x _settextcolor _setbkcolor -_settextposition 

a | 


#Hinclude <conio.h> 
#finclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [88]; 


void main() 
{ 


/* Save original foreground, background, and text position. */ 
short blink, fgd, oldfgd; 

long bgd, oldbgd; 

struct rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 


toa 
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/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 
{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bad < 8; bgd++ ) 
{ 
_setbkcolor( bgd ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1); 
_settextcolor( 7 ); . 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 


/* Loop through 16 foreground colors. */ 
for( fgd = @; fad < 16; fgd++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 
_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 
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Description Get the current position and return it as a structure. 
#include <graph.h> 


struct xycoord far _getcurrentposition( void ); 
struct _wxycoord far _getcurrentposition_w( void ); 
Remarks The _getcurrentposition functions return the coordinates of the current graphics output 


position. The _getcurrentposition function returns the position as an xycoord structure, 
defined in GRAPH.H. 


The xycoord structure contains the following elements: 


Element Description 
short xcoord — x coordinate 
short ycoord y coordinate 


The _getcurrentposition_w function returns the position as an_wxycoord structure, de- 
fined in GRAPH.H. 


The _wxycoord structure contains the following elements: 


Element Description 
double wx window x coordinate 
double wy window y coordinate 


The current position can be changed by the _lineto, _moveto, and _outgtext functions. 


The default position, set by_setvideomode, _setvideomoderows, or _setviewport, is the 
center of the viewport. 


Only graphics output starts at the current position; these functions do not affect text output, 
which begins at the current text position. (See _settextposition for more information.) 


Return Value The _getcurrentposition function returns the coordinates of the current graphics output 
position. There is no error return. 
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Compatibility O ANSI @ DOS OF OS2 O UNIX O XENIX 


See Also _grstatus, _lineto functions, _moveto functions, _outgtext 


Example 


/* GCURPOS.C: This program sets a random current location, then gets that 
* location with _getcurrentposition. 
*/] 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <conio.h> 
#Hinclude <graph.h> 


char buffer({255); 


void main() 

{ . 
struct videoconfig vc; 
struct xycoord position; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 

_getvideoconfig( &vc ); 


/* Move to random location and report that location. */ 5 

_moveto( rand() % vc.numxpixels, rand() % vc.numypixels ); 

position = _getcurrentposition(); 

sprintf( buffer, "x = 4d, y = #d", position.xcoord, position.ycoord ); 
_settextposition( 1, 1 ); 

_outtext( buffer ); 


getch(); 
_setvideomode( _DEFAULTMODE ); 
} 
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Description Gets the current working directory. 
#include <direct.h> Required only for function declarations 


char *getcwd( char *buffer, int maxlen ); 


buffer Storage location for path name 
maxlen Maximum length of path name 
Remarks The getewd function gets the full path name of the current working directory and stores it 


at buffer. The integer argument maxlen specifies the maximum length for the path name. 
An error occurs if the length of the path name (including the terminating null character) 
exceeds maxlen. 


The buffer argument can be NULL; a buffer of at least size maxlen (more only if neces- 
sary) will automatically be allocated, using malloc, to store the path name. This buffer can 
later be freed by calling free and passing it the getcwd return value (a pointer to the allo- 
cated buffer). 


Return Value The getcwd function returns a pointer to buffer. A NULL return value indicates an error, 
and errno is set to one of the following values: 


Value Meaning 


ENOMEM Insufficient memory to allocate maxlen bytes (when a NULL 
argument is given as buffer) 


ERANGE Path name longer than maxlen characters 
Compatibility O ANS! @ DOS HH OS/2 Mf UNIX =) XENIX 


See Also chdir, mkdir, rmdir 


Example 


/* This program places the name of the current directory in the buffer 
* array, then displays the name of the current directory on the screen. 
* Specifying a length of _MAX_DIR leaves room for the longest legal 
* directory name. 

*/ 
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#Hinclude <direct.h> 
#Hinclude <stdlib.h> 
fHinclude <stdio.h> 


void main() 
( 
char buffer{MAX_DIR]; 


/* Get the current working directory: */ 
if( getcwd( buffer, _MAX_DIR ) == NULL ) 
perror( "getcwd error” ); 
else 
printf( "s\n", buffer ); 


Output 


C:\LIBREF 
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Description Gets full path name of current working directory, including disk drive. 
#include <direct.h> Required only for function declarations 
char *_getdcwd( int drive, char *buffer, int maxlen ); 


drive Disk drive 


buffer Storage location for path name 
maxlen Maximum length of path name 
Remarks The _getdcwd function gets the full path name of the current working directory, including 


disk drive specification, and stores it at buffer. The argument maxlen specifies the maxi- 
mum length for the path name. An error occurs if the length of the path name (including 
the terminating null character) exceeds maxlen. 


The drive argument specifies the drive (0 = default drive, 1=A, 2=B, etc.). The buffer argu- 
ment can be NULL; a buffer of at least size maxlen (more only if necessary) will automat- 
ically be allocated, using malloc, to store the path name. This buffer can later be freed by 
calling free and passing it the _getdewd return value (a pointer to the allocated buffer). 


Return Value The _getdcwd function returns buffer. A NULL return value indicates an error, and errno 
is set to one of the following values: 


Value Meaning 
ENOMEM Insufficient memory to allocate maxlen bytes (when a NULL 
: argument is given as buffer) 
ERANGE Path name longer than maxlen characters 
Compatibility O ANS! @ DOS #8 OS 0 UNIX OO XENIX 
See Also chdir, getcwd, _getdrive, mkdir, rmdir 


Example 


/* GETDRIVE.C illustrates. drive functions including: 
_getdrive _chdrive _getdcwd 
*/ 
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#Hinclude <stdio.h> 
#Hinclude <conio.h> 
fHinclude <direct.h> 
dFinclude <stdlib.h> 


void main() 

{ 
int ch, drive, curdrive; 
Static char path[_MAX_PATH]; 


/* Save current drive. */ 
curdrive = _getdrive(); 


printf( "Available drives are: \n" ); 


/* If we can switch to the drive, it exists. */ 
for( drive = 1; drive <= 26; drivet+ ) 
if( !_chdrive( drive ) ) 
printf( “%c: ", drive + 'A' - 1); 


while( 1 ) 
{ 
printf( "\nType drive letter to check or ESC to quit: " ); 
ch = getch(); 
if( ch == 27 ) 
break; 
if( isalpha( ch ) ) 
putch( ch ); 
if( _getdcwd( toupper( ch ) - ‘A' + 1, path, _MAX_PATH ) != NULL ) 
printf( “\nCurrent directory on that drive is %s\n", path ); 
} 


/* Restore original drive. This is only necessary for DOS. Under O0S/2 
* the current drive of the calling process is always restored. 
=} 

_chdrive( curdrive ); 

printf( "\n" ); 
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Output 


Available drives are: 

A: B: C: 

Type drive letter to check or ESC to quit: q 
Type drive Jetter to check or ESC to quit: a 
Current directory on that drive is A:\ 


Type drive letter to check or ESC to quit: c 
Current directory on that drive is C:\LIBREF 


Type drive letter to check or ESC to quit: 
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Description Gets the current disk drive. 
#include <direct.h> 


int _getdrive( void ); 


Remarks The _getdrive function returns the current working drive (1=A, 2=B, etc.). 
Return Value The return value is stated above. There is no error return. 

Compatibility O ANS! @ DOS WM OS/2 OF UNIX O XENIX 

See Also _chdrive, _dos_getdrive, dos setdrive, getcwd, getdcwd 


Example See the example for _getdcwd. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets a value from the environment table. 

#include <stdlib.h> Required only for function declarations 
char *getenv( const char *varname )s 

varname | Name of environment variable 


The getenv function searches the list of environment variables for an entry corresponding 
to varname. Environment variables define the environment in which a process executes. 
(For example, the LIB environment variable defines the default search path for libraries to 
be linked with a program.) Because the getenv function is case sensitive, the varname vari- 
able should match the case of the environment variable. 


The getenv function returns a pointer to an entry in the environment table. It is, however, 
only safe to retrieve the value of the environment variable using the returned pointer. To 
modify the value of an environmental variable, use the putenv function. 


The getenv and putenv functions use the copy of the environment contained in the global 
variable environ to access the environment. Programs that use the envp argument to main 
and the putenv function may retrieve invalid information. The safest programming prac- 
tice is to use getenv and putenv. 


The getenv function returns a pointer to the environment table entry containing the current 
string value of varname. The return value is NULL if the given variable is not currently 
defined. 


MANS! M@ DOS HM OS/2 WF UNIX Mf XENIX 


The getenv function operates only on the data structures accessible to the run-time library 
and not on the environment “segment” created for a process by DOS or OS/2. 


putenv 


/* GETENV.C: This program uses getenv to retrieve the LIB environment 
* variable and then uses putenv to change it to a new value. 


sats 


#Finclude <stdlib.h> 
#Hinclude <stdio.h> 
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main() 
{ 
char *libvar; 


/* Get the value of the LIB environment variable. */ 
libvar = getenv( "LIB" ); 
if( libvar != NULL ) 

printf( “Original LIB variable is: %s\n", libvar ); 


/* Attempt to change path. Note that this only affects the environment 
* variable of the current process. The command processor's environment 
* is not changed... 

a | 
putenv( “LIB=c:\\mylibs;c:\\yourlib" ); 


/* Get new value. */ 
libvar = getenv( "LIB" ); 
if( libvar != NULL ) 
printf( “New LIB variable is: %s\n", libvar ); 


Output 


Original LIB variable is: C:\LIB 
New LIB variable is: c:\mylib;c:\yourlib 
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Description 


Remarks 


Return Value 
Compatibility 


See Also 


Example. 


Gets the current fill mask for some graphics routines. 

#include erupts 

unsigned char _far * _far _getfillmask( unsigned char _far *mask ); 
mask Mask array 


Some graphics routines (_ellipse, floodfill, pie, polygon, and rectangle) can fill part 
or all of the screen with the current color or background color. The fill mask controls the 
pattern used for filling. 


The _getfillmask function returns the current fill mask. The mask is an 8-by-8-bit array, in 
which each bit represents a pixel. If the bit is 1, the corresponding pixel is set to the current 
color; if the bit is 0, the pixel is left unchanged. The mask is repeated over the entire fill 
area. If no fill mask is set, or if mask is NULL, a solid (unpatterned) fill is performed using 
the current color. 


If no mask is set, the function returns NULL. 
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_ellipse functions, _floodfill, _pie functions, _ polygon functions, _rectangle functions, 
_Setfillmask 


/* GFILLMSK.C: This program illustrates _getfillmask and _setfillmask. */ 


#Hinclude <conio.h> 
#Hinclude <stdlib.h> 
#Hinclude-<graph.h> 
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void ellipsemask( short xl, short yl, short x2, short y2, char _far *newmask ); 


unsigned char mask1[8] = { 0x43, 0x23, Ox7c, Oxf7, Ox8a, Ox4d, Ox78, Bx39 }; 
unsigned char mask2(8] = { @x18, Oxad, @xc®@, 9x79, Oxf6, Oxc4, Oxa8B, Ox23 }; 


char oldmask[8]; 


void main() 


{ 


} 


int loop; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1); 


/* Set first fill mask and draw rectangle. 
_setfillmask( maskl ); 


ad 


_rectangle( _GFILLINTERIOR, 20, 20, 100, 100 ); 


getch(); 


/* Call routine that saves and restores mask. */ 


ellipsemask( 60, 60, 158, 150, mask2 ); 
getch(); 


/* Back to original mask. */ 
_rectangle( _GFILLINTERIOR, 120, 128, 190, 
getch(); 


_setvideomode( _DEFAULTMODE ); 


198 ) 


/* Draw an ellipse with a specified fill mask. */ 
void ellipsemask( short xl, short yl, short x2, short y2, char _far *newmask ) 


{ 


unsigned char savemask[8]; 


_getfillmask( savemask ); 
_setfillmask( newmask ); 
_ellipse( _GFILLINTERIOR, xl, yl, x2, y2 ); 
_setfillmask( savemask ); 


/* 
/* 
/* 
/* 


Save mask 

Set new mask 
Use new mask 
Restore original 


a 4 
*7 
xy 
mf 
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Description Gets the current font characteristics. 
#include <graph.h> 
short far getfontinfo( struct fontinfo far *fontbuffer ); 
fontbuffer Buffer to hold font information 
Remarks The _getfontinfo function gets the current font characteristics and stores them ina 


_fontinfo structure, defined in GRAPH.H. 


The _fontinfo structure contains the following elements: 


Element Contents 
int type Specifies vector (1) or bit-mapped (0) font 
int ascent Specifies pixel distance from top to baseline 
int pixwidth Specifies the character width in pixels; 0 indicates a 
proportional font 
int pixheight Specifies the character height in pixels 
int avgwidth Specifies the average character width in pixels 
char filename [81] Specifies the file name, including the path 
char facename [32] Specifies the font name 
Return Value ao nee function returns a negative number if a font has not been registered or 
oaded. 


Compatibility C) ANS! @ DOS OF O0S/7 O UNIX OC XENIX 


See Also _getgtextextent, outgtext, registerfonts, setfont, _setgtextvector, 
_unregisterfonts 


Example See the example for _outgtext. 


365 _getgtextextent 
Description Gets the width in pixels of font-based text. 

#include <graph.h> 

short far _getgtextextent( unsigned char far *fext ); 

text Text to be analyzed 
Remarks The _getgtextextent function returns the width in pixels that would be required to print the 


Return Value 


Compatibility 


See Also 


Example 


text string using _outgtext with the current font. 
This function is particularly useful for determining the size of text that uses proportionally 
spaced fonts. 


The _getgtextextent function returns the width in pixels. It returns —1 if a font has not 
been registered. 


O ANS! @ DOS OF O0S7?2 O UNIX O XENIX 
_getfontinfo, outgtext, registerfonts, setfont, _unregisterfonts 


See the example for _outgtext. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Changes the orientation of font text output. 
#include <graph.h> 
struct xycoord far _getgtextvector( void ); 


The _getgtextvector function gets the current orientation for font text output. The current 
orientation is used in calls to the _outgtext function. 


The text-orientation vector, which determines the direction of font-text rotation on the 
screen, is returned in a structure of type xycoord. The xcoord and ycoord members of the 
structure describe the vector. The text-rotation options are shown below: 


Gy) Text Orientation 

(1,0) Horizontal text (default) 

(0,1) Rotated 90 degrees counterclockwise 
(-1,0) Rotated 180 degrees 

(0,-1) Rotated 270 degrees counterclockwise 


The _getgtextvector function returns the current text-orientation vector in a structure of 
type xycoord. 
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_getgtextextent, grstatus, outgtext, setfont, _setgtextvector 


367 _getimage Functions 
Description Store images in buffers. 
#include <graph.h> 
void far _getimage( short x/, short y/, short x2, short y2, char _huge *image ); 
void far _getimage_w( double wx/, double wy/, double wx2, double wy2, 
char _huge *image ); 
void far _getimage_wxy(struct_wxycoord far *pwxyl, 
struct_wxycoord _far *pwxy2, char _huge “image ); 
xl, yl Upper-left corner of bounding rectangle 
x2, y2 Lower-right comer of bounding rectangle 
wxl, wyl Upper-left corner of bounding rectangle 
wx2, wy2 Lower-right comer of bounding rectangle 
pwxyl Upper-left corner of bounding rectangle 
pwxy2  Lower-right comer of bounding rectangle 
image Storage buffer for screen image 
Remarks The _getimage functions store the screen image defined by a specified bounding rectangle 


Return Value 


Compatibility 


into the buffer pointed to by image. 


The _getimage function defines the bounding rectangle with the view coordinates (xl, yl) 
and (x2, y2). 


The _getimage_w function defines the bounding rectangle with the window coordinates 
(wxl, wyl) and (wx2, wy2). 


The _getimage_wxy function defines the bounding rectangle with the window-coordinate 
pairs pwxyl and pwxy2. 


The buffer must be large enough to hold the image. You can determine the size by calling 
the appropriate _imagesize function at run time, or by using the formula described on the 
_imagesize reference page. . 


None. Use _grstatus to check success. 
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See Also _grstatus, _imagesize functions, _putimage functions 


Example 


e GIMAGE.C: This example illustrates animation routines including: 


_imagesize _getimage _putimage 
a 


#Hinclude <conio.h> 
#Hinclude <stddef.h> 
include <stdlib.h> 
#Hinclude <malloc.h> 
#Hinclude <graph.h> 


short action[5] = { _GPSET, _GPRESET, _GXOR, _GOR, _GAND 
char *descrip(5] = { “PSET ", "PRESET", "XOR ", “OR ", "AND " 


—— 
we we 


void exitfree( char _huge *buffer ); 


void main() 

{ 
char _huge *buffer; /* Far pointer (with _fmalloc) could be used. */ 
long imsize; 
Short i, x, y = 3G; 


if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1); 


/* Measure the image to be drawn and allocate memory for it. */ 
imsize = (size_t)_imagesize( -16, -16, +16, +16 ); 
buffer = halloc( imsize, sizeof( char ) ); 
if ( buffer == (char _far *)NULL ) 
exit( 1 ); 


_setcolor( 3 ); 
for ( i =@; i < 53 it+ ) 
( 
/* Draw ellipse at new position and get a copy of it. */ 
x = 50; y t= 40; 
_ellipse( _GFILLINTERIOR, x - 15, y - 15, x + 15, y +15 ); 
_getimage( x - 16, y - 16, x + 16, y + 16, buffer ); 
if( _grstatus() ) 
exitfree( buffer ); /* Quit on error aed 
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/* Display action type and copy a row of ellipses with that type. */ 
_settextposition( 1, 1 ); 

_outtext( descripLli] ); 

while( x < 260 ) 

{ 


x += 5; 
_putimage( x - 16, y - 16, buffer, action{[i] ); 
if( _grstatus() < @ ) /* Ignore warnings, quit on errors. */ 


exitfree( buffer ); 
} 
getch(); 
} 
exitfree( buffer ); 
} 


void exitfree( char _huge *buffer ) 
{ 
hfree( buffer ); 
exit( !_setvideomode( _DEFAULTMODE ) ); 
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Description Gets the current line style. 
#include <graph.h> 
unsigned short far _getlinestyle( void ); 


Remarks Some graphics routines (_lineto, polygon, and _rectangle) output straight lines to the 
screen. The type of line can be controlled with the current line-style mask. 


The _getlinestyle function returns the current line-style mask. The mask is a 16-bit array 
in which each bit represents a pixel in the line being drawn. If the bit is 1, the correspond- 
ing pixel is set to the color of the line (the current color). If the bit is 0, the corresponding 
pixel is left unchanged. The mask is repeated over the length of the line. The default mask 
is OxFFFF (a solid line). 


Return Value If no mask has been set, _getlinestyle returns the default mask. 
Compatibility O ANS| @ DOS OF O0S?2 UO UNIX O XENIX 


See Also _lineto functions, _polygon functions, _rectangle functions, _setlinestyle, 
_setwritemode 


Example 
/* GLINESTY.C: This program illustrates _setlinestyle and _getlinestyle. */ 


#Hinclude <conio.h> 
d#tinclude <stdlib.h> 
#Hinclude <graph.h> 


void zigzag( short xl, short yl, short size ); 


void. main() 


{ 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 


/* Set line style and draw rectangle. */ 
_setlinestyle( @x4d ); 

_rectangle( _GBORDER, 10, 10, 60, 60 ); 
getch(); 
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/* Draw figure with function that changes and restores line style. */ 
zigzag( 180, 108, 98 ); 
getch(); 


/* Original style reused. */ 
_rectangle( _GBORDER, 190, 190, 130, 130 ); 
getch(); 


_setvideomode( _DEFAULTMODE ); 
} 


/* Draw box with changing line styles. Restore original style. */ 
void zigzag( short xl, short yl, short size ) 
{ 
short x, y, oldcolor; 
unsigned short oldstyle; 
unsigned short style[16] = ({ @x@@01, Ox@0O3, OxO9B07, OxBBOT, 
OxOB1f, OxOB3F, OxBB7F, WxBWfFf, 
OxO1lff, OxO3ff, OxO7FF, OxOfff, 
Oxifff, Ox3fff, Ox7ffF, Oxffff }; 


oldcolor = _getcolor(); 
oldstyle = _getlinestyle(); /* Save old line style. * / 
for( x = 3, y = 3; x < size; x t= 3, y t= 3 ) 
{ 
_setcolor( x %2 16 ); 
_setlinestyle( style{x % 16] ); /* Set and use new line styles */ 
_rectangle( _GBORDER, xl - x, yl - y, xl +x, yl + y ); 
} 
_setlinestyle( oldstyle ); 
_setcolor( oldcolor ); 


. /* Restore old line style. */ 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


Gets physical coordinates. 

#include <graph.h> 

struct xycoord far _getphyscoord( short x, short y ); 

x,y View coordinates to translate 

The _getphyscoord function translates the view coordinates (x, y) to physical coordinates 


and returns them in an xycoord structure, defined in GRAPH.H. 


The xycoord structure contains the following elements: 


Element Description 
short xcoord. x coordinate 
short ycoord y coordinate 
None. 


O ANS! M@ DOS OF 0S O UNIX O XENIX 
_getviewcoord functions, _grstatus, _setvieworg, _setviewport 


See the example for _setwindow. 


373 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


getpid 


Gets the process identification. 
#include <process.h> Required only for function declarations 
int getpid( void ); 


The getpid function returns the process ID, an integer that uniquely identifies the calling 
process. 


The getpid function returns the process ID. There is no error return. 


O ANS! @ DOS # OS/2 WM UNIX” Wf XENIX 


mktemp | 


/* GETPID.C: This program uses getpid to obtain the process ID and 
* then prints the ID. 
*/ 


#Hinclude <stdio.h> 
#Hinclude <process.h> 


void main( ) 


{ 


/* If run from DOS, shows different ID for DOS than for DOS shell. 
* If execed or spawned, shows ID of parent. 


*/ 


. 


printf( "\nProcess id of pdrent: %d\n", getpid() ); 


} 


Output 


Process id of parent: 828 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Get pixel values. 
#include <graph.h> 


short far _getpixel( short x, short y ); 
short far _getpixel_w( double wx, double wy ); 


x,y Pixel position 


wx, wy Pixel position 


The functions in the _getpixel family return the pixel value (a color index) at a specified 
location. The _getpixel function uses the view coordinate (x, y). The _getpixel_w function 
uses the window coordinate (wx, wy). The range of possible pixel values is determined by 
the current video mode. The color translation of pixel values is determined by the current 
palette. 


If successful, the function returns the color index. If the function fails (for example, the 
point lies outside the clipping region, or the program is in a text mode), it returns -1. 


O ANS! @ DOS 0 OS/2 O UNIX O XENIX 


_getvideoconfig, _grstatus, _remapallpalette, remappalette, _selectpalette, 
_Setpixel functions, _setvideomode 


ie GPIXEL.C: This program assigns different colors to randomly 
* selected pixels. 


sad 


#Hinclude <conio.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 


void main() 


short xvar, yvar; 
struct videoconfig vc; 
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/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &vc ); 


/* Draw filled ellipse to turn on certain pixels. */ 
_ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6, 
ve.numxpixels / 6 * 5, vc.numypixels / 6 * 5 ); 


/* Draw random pixels in random colors... */ 
while( !kbhit() ) 
{ 
/* ...but only if they are already on (inside the ellipse). */ 
xvar = rand() % vc.numxpixels; 
yvar = rand() % vc.numypixels; 
if( _getpixel( xvar, yvar ) !=@ ) 


_setcolor( rand() % 16 ); 
_setpixel( xvar, yvar ); 
} 
} 


getch(); /* Throw away the keystroke. */ 
_setvideomode( _DEFAULTMODE ); 


gets 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 
/* GETS.C */ 


dhinclude <stdio. 


void main() 
{ 


Gets a line from the stdin stream. 

#include <stdio.h> 

char *gets( char *buffer ); 

buffer _ Storage location for input string 


The gets function reads a line from the standard input stream stdin and stores it in buffer. 
The line consists of all characters up to and including the first newline character (\n). The 
gets function then replaces the newline character with a null character (°\0’) before return- 
ing the line. In contrast, the fgets function retains the newline character. 


If successful, the gets function returns its argument. A NULL pointer indicates an error or 
end-of-file condition. Use ferror or feof to determine which one has occurred. 


mM ANS! @ DOS WM OS/2 UNIX Mf XENIX 


fgets, fputs, puts 


h> 


char line({81]; 


printf( "Input a string: " ); 


gets( line ); 
printf( "The 


Output 


Input a string: 


line entered was: %s\n", line ); 


This is a string 


The line entered was: This is a string 


377 _gettextcolor 
Description Gets the current text color. 

#include <graph.h> 

short far _gettextcolor( void ); 
Remarks The _gettextcolor function returns the color index of the current text color. The text color 


Return Value 


Compatibility 


See Also 


Example 


is set by the _settextcolor function and affects text output with the _outtext and_outmem 
functions only. The _setcolor function sets the color for font text output using the 
_outgtext function. 


The default is 7 in test modes; it is the highest legal color index of the current palette in 
graphics modes. 

The _gettextcolor function returns the color index of the current text color. 

O ANS| @ DOS WM OS/7 OF UNIX OO XENIX 


_getvideoconfig, _remappalette, selectpalette, setcolor, _settextcolor 


See the example for _gettextposition. 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Gets the current cursor attribute. 
#include <graph.h> 
short far _gettextcursor( void ); 


The _gettextcursor function returns the current cursor attribute (i.e., the shape). This func- 
tion works only in text video modes. . 


The function returns the current cursor attribute, or —1 if an error occurs (such as a call to 
the function in a graphics mode). 


O ANS! @ DOS WM OS72 CO UNIX O XENIX 
_displaycursor, _grstatus, _settextcursor 


See the example for _settextcursor. 
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Description Gets the current text position. 
#include <graph.h> 


struct rccoord far _gettextposition( void ); 


<— 


Remarks The _gettextposition function returns the current text position as an recoord structure, 
defined in GRAPH.H. 


The recoord structure contains the following elements: 


Element Description 
short row Row coordinate 
short col Column coordinate 
Remarks The text position given by the coordinates (1,1) is defined as the upper-left corner of the 


text window. 


Text output from the _outtext and _outmem functions begins at the current text position. 
Font text is not affected by the current text position. Font text output begins at the current 
graphics output position, which is a separate position. 


Return Value None. 
Compatibility O ANS! 9 DOS 8 OS72 O UNIX O XENIX 


See Also _getcurrentposition functions, _moveto functions, _outmem, _ outtext, 
_Settextposition, _settextwindow, _wrapon 


Example 

/* QUTTXT.C: This example illustrates text output functions: 

* _gettextcolor _getbkcolor -_gettextposition  _outtext 
* _settextcolor _setbkcolor -_settextposition 

*/ . 


dHinclude <conio.h> 
dHinclude <stdio.h> 
dHinclude <graph.h> 
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char buffer [80]; 


void main() 
{ 


/* Save original foreground, background, and text position. */ 
short blink, fgd, oldfgd; 

long bgd, oldbgd; 

struct rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 


/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 
{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bgd < 8; bgd++ ) 
{ 
_setbkcolor( bgd ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: @d Fore:", bad ); 
_outtext( buffer ); 


/* Loop through 16 foreground colors. */ 
for( fgd = @; fad < 16; fgd++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 


381 _gettextwindow 
Description Gets the boundaries of the current text window. 

#include <graph.h> 

void far _gettextwindow( short far *r/,short far *c/,short far *r2, 

short _far *c2 ); 

rl | Top row of current text window 

cl Leftmost column of current text window 

r2 Bottom row of current text window 

c2 Rightmost column of current text window 
Remarks The _ gettextwindow function finds the boundaries of the current text window. The text 


Return Value 


Compatibility 


See Also 


Example 


window is the region of the screen to which output from the _outtext and _outmem func- 
tions is limited. By default, this is the entire screen, unless it has been redefined by the 
_settextwindow function. 


The window defined by _settextwindow has no effect on output from the _outgtext func- 
tion. Text displayed with _outgtext is limited to the current viewport. 
None. 


O ANS! M@ DOS WM OS/72 OF UNIX UO XENIX 


_gettextposition, _outmem, _outtext, scrolltextwindow, _settextposition, 
_sSettextwindow, _wrapon 


See the example for _scrolltextwindow. 
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Description — 


Remarks 


Gets graphics video configuration information. 


#include <graph.h> 


struct videoconfig far * far _getvideoconfig( struct videoconfig far *config ); 


config 


Configuration information 


The _getvideoconfig function returns the current graphics environment configuration in a 
videoconfig structure, defined in GRAPH.H. 


The values returned reflect the currently active video adapter and monitor, as well as the 


current video mode. 


The videoconfig structure contains the following members, each of which is of type short: 


Member 
adapter 
bitsperpixel 
memory 
mode 
monitor 
numcolors 
numtextcols 
numtextrows 
numvideopages 
numxpixels 


numypixels 


Contents 

Active display adapter 

Number of bits per pixel 

Adapter video memory in kilobytes 
Current video mode 

Active display monitor 

Number of color indices 

Number of text columns available 
Number of text rows available 
Number of available video pages 
Number of pixels on the x axis 


Number of pixels on the y axis 
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The values for the adapter member of the videoconfig structure are given by the manifest 
constants shown in the list below. For any applicable adapter (_CGA, EGA, or VGA), 
the corresponding Olivettia adapter (_ OCGA, OEGA, or_OVGA) represents a superset 
of graphics capabilities. 


Adapter Constant Meaning 

_CGA Color Graphics Adapter 

_EGA Enhanced Graphics Adapter 

_HGC Hercules@ Graphics Card 

_MCGA Multicolor Graphics Array 

_MDPA Monochrome Display Printer Adapter 
_OCGA Olivetti (AT&T@) Color Graphics Adapter 
_OEGA Olivetti (AT&T) Enhanced Graphics Adapter 
_OVGA Olivetti (AT&T) Video Graphics Array 
_VGA Video Graphics Array 


The values for the monitor member of the videoconfig structure are given by the manifest 
constants listed below: 


Monitor Constant Meaning 

_ANALOG Analog monochrome and color 

_ANALOGCOLOR Analog color only 

_ANALOGMONO Analog monochrome only 

_COLOR Color (or enhanced monitor emulating a color monitor) 
_ENHCOLOR Enhanced color 

_MONO Monochrome monitor 


In every text mode, including monochrome, the _getvideoconfig function returns the value 
32 for the number of available colors. The value 32 indicates the range of values (0-31) 
accepted by the _settextcolor function. This includes 16 normal colors (0-15) and 16 
blinking colors (16-31). Blinking is selected by adding 16 to the normal color index. Be- 
cause monochrome text mode has fewer unique display attributes, some color indices are 
redundant. However, because blinking is selected in the same manner, monochrome text 
mode has the same range (O—31) as other text modes. 
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Return Value 


Compatibility 


See Also 


Example 


/* Q@VIDCFG.C: This program displays information about the current 


The _ getvideoconfig function returns the video configuration information in a structure, as 
noted above. There is no error return. 


O ANSI 


m@ DOS 


B OS/2 


O UNIX CO XENIX 


_setvideomode, _setvideomoderows 


* video configuration. 


] 


#Hinclude <stdio.h> 
#Hinclude <graph.h> 


void main() 


{ 


struct videoconfig vc; 


short 


char 


Cc; 
b[580] 


_getvideoconfig( &vc ); 


/* Buffer for string */ 


* Write all information to a string, then 


+= 
+= 


/ 
c 
C 
c 
c 
Cc = 
c 
C 
C 
C 
C 
Cc += 


sprintf ( 
sprintf ( 
sprintf ( 


= sprintf ( 


sprintf ( 
sprintf ( 
sprintf ( 
sprintf ( 
sprintf ( 
sprintf ( 
sprintf ( 


b, 


> i A © EE OO OE OO 
t++eeeteteeeest 


_outtext( b ); 


"X pixels: 

"Y pixels: 
"Text columns: 
"Text rows: 
"Colors: 
"Bits/pixel: 
"Video pages: 
"Mode: 
"Adapter: 
“Monitor: 
“Memory: 


4d\n", 
Zd\n", 
Zd\n", 
d\n", 
4d\n", 
Zd\n", 
Zd\n", 
4d\n", 
4d\n", 
Zd\n", 
Zd\n", 


output string. */ 
vc.numxpixels ); 
vc.numypixels ); 
ve.numtextcols ); 
vc.numtextrows ); 
ve.numcolors ); 
vc.bitsperpixel ); 
vc.numvideopages ); 
vc.mode ); 
vc.adapter ); 
vc.monitor ); 
vc.memory ); 
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Output 

X pixels: 4) 
Y pixels: B 
Text columns: 88 
Text rows: 25 
Colors: a 


Bits/pixel: 9Q 
Video pages: 1 


Mode: 3 
Adapter; 8 
Monitor: 24 


Memory: 256 
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Description 


Remarks 


Return Value 


Translate coordinates to view coordinates. 
#include <graph.h> 


struct xycoord far _getviewcoord( short x, short y ); 
struct xycoord far _getviewcoord_w( double wx, double wy ); 


struct xycoord far _getviewcoord_wxy( struct _wxycoord far *pwxyl ); 


x,y Physical point to translate 
wx, wy Window point to translate 
pwxyl Window point to translate 


The _getviewcoord routines translate the specified coordinates (x, y) from one coordinate 


system to view coordinates and then return them in an xycoord structure, defined in 
GRAPH.H. The xycoord structure contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


The various _getviewcoord routines translate in the following manner: 


Routine Translation 

_getviewcoord Physical coordinates (x, y) to view coordinates 
_getviewcoord_w Window coordinates (wx, wy) to view coordinates 
_getviewcoord_wxy Window coordinates structure (pwxy/ ) to view coordinates 


C 5.1 Version Difference In Microsoft C version 5.1, the function_getviewcoord was called 
_getlogcoord. 


The _getviewcoord function returns the coordinates as noted above. There is no error 
return. 
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Compatibility O ANS! M@ DOS OF 0S72 OO UNIX OO XENIX 
See Also _getphyscoord, _getwindowcoord, _grstatus 


Example See the example for _setwindow. 


_getvisualpage | 388 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets the current visual page number. 

#include <graph.h> 

short far _getvisualpage( void ); 

The _getvisualpage function returns the current visual page number. 


The function returns the number of the current visual page. All hardware combinations sup- 
port at least one page (page number 0). In OS/2, only page 0 is available. 


O ANS! @ DOS WM OS/2 OF UNIX O XENIX 


_getactivepage, _gettextcolor, _gettextposition, _outtext, _setactivepage, 
_settextcolor, _settextposition, settextwindow, _setvideomode, 
_setvisualpage, _wrapon 


See the example for _getactivepage. 


389 getw 
Description Gets an integer from a stream. 

#include <stdio.h> 

int getw( FILE *stream ); 

stream Pointer to FILE structure 
Remarks The getw function reads the next binary value of type int from the file associated with 


Return Value 


Compatibility 


See Also 


Example 
/* GETW.C: This 


stream and increments the associated file pointer (if there is one) to point to the next un- 
read character. The getw function does not assume any special alignment of items in the 
stream. 


The getw function returns the integer value read. A return value of EOF may indicate an 
error or end-of-file. However, since the EOF value is also a legitimate integer value, feof 
or ferror should be used to verify an end-of-file or error condition. 


O ANS! @ DOS MOS HW UNIX’ Wi XENIX 


The getw function is provided primarily for compatibility with previous libraries. Note 
that portability problems may occur with getw, since the size of the int type and the order- 
ing of bytes within the int type differ across systems. 


putw 


program uses getw to read a word from a stream, 


* then performs an error check. 


*/ F 


dFinclude <stdio. 


h> 


dtinclude <stdlib.h> 


void main() 


( 


FILE *stream; 
int i; 
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if( (stream = fopen( "getw.c", "rb" )) == NULL ) 
printf( "Couldn't open file\n" ); 

else 

{ 
/* Read a word from the stream: */ 
i = getw( stream ); 


/* If there is an error... */ 
if( ferror( stream ) ) 
printf( "getw failed\n" ); 
clearerr( stream ); 
} 
else 
printf( "First data word in file: @x%.4x\n", i ); 
fclose( stream ); 


Output 


First data word in file: Ox2a2f 
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Description Translates view coordinates to window coordinates. 

#include <graph.h> 

struct _wxycoord far _getwindowcoord( short x, short y); 

x,y Physical point to translate 
Remarks The _getwindowcoord function translates the view coordinates (x, y) to window coordi- 


Return Value 


Compatibility 


See Also 


Example 


nates and returns them in the _wxycoord structure, defined in GRAPH.H. 


The _wxycoord structure contains the following elements: 


Element Description 
double wx x coordinate 
double wy y coordinate 


The function returns the coordinates in the _wxycoord structure. There is no error return. 
O ANSI @ DOS O OS/2 O UNIX O XENIX 
_getphyscoord, _getviewcoord functions, _moveto functions, _setwindow 


See the example for _setwindow. 


_getwritemode | | 392 


Description Gets the current logical mode for line drawing. 
#include <graph.h> 
short far _getwritemode( void ); 
Remarks The _getwritemode function returns the current logical write mode, which is used when 


drawing lines with the _lineto, polygon, and _rectangle functions. 


The default value is_GPSET, which causes lines to be drawn in the current graphics color. 
The other possible return values are_GXOR, GAND, GOR, and _GPRESET. See 
_putimage for more details on these manifest constants. 


Return Value The _getwritemode function returns the current logical write mode, or —1 if not in 
graphics mode. 


Compatibility O ANS! M@ DOS OF 0S/2 O UNIX O XENIX 


See Also _grstatus, lineto functions, _putimage functions, _rectangle functions, 
_setcolor, _setlinestyle, _setwritemode 


Example 

/* QGWRMODE.C: This program illustrates _getwritemode and _setwritemode. */ 
#Hinclude <conio.h> 

#tinclude <stdlib.h> 

#Hinclude <graph.h> 


short wmodes[5] = { _GPSET, _GPRESET, _GXOR, _GOR, _GAND } 
char *wmstr(5]) = { "PSET ", "PRESET", "XOR ", “OR ", "AND "™ } 


void box( short x, short y, short size, short writemode, short fillmode ); 


void main() 
{ 
short i, x, y; 
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/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1); | 


x =y = 70; 
box( x, y, 58, _GPSET, _GFILLINTERIOR ); 
_setcolor( 2 ); 
box( x, y, 48, _GPSET, _GFILLINTERIOR ); 
for( i = @; i < 5; i++ ) 
{ 
_settextposition( 1, 1 ); 
_outtext( wmstrLil ); 
box( x += 12, y += 12, 58, wmodesCi], _GBORDER ); 
getch(); 
} 
_setvideomode( _DEFAULTMODE ); 
} 


void box( short x, short y, short size, short writemode, short fillmode ) 


{ 
short wm, side; 


wm = _getwritemode(); /* Save write mode and set new. */ 
_setwritemode( writemode ); 

_rectangle( fillmode, x - size, y - size, x + size, y + size ); 
_setwritemode( wm ); /* Restore original write mode. */ 
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Description Converts a time value to a structure. 
#include <time.h> 
struct tm *gmtime( const time_t *timer ); 
timer Pointer to stored time 


Remarks The gmtime function converts the timer value to a structure. The timer argument repre- 
sents the seconds elapsed since 00:00:00, January 1, 1970, Greenwich mean time. This 
value is usually obtained from a call to the timer function. 


The gmtime function breaks down the timer value and stores it in a structure of type tm, 
defined in TIME.H. (See asctime for a description of the structure members.) The struc- 
ture result reflects Greenwich mean time, not local time. 


The fields of the structure type tm store the following values, each of which is an int: 


Field Value Stored 

tm_sec Seconds 

tm_min Minutes 

tm_hour Hours (0-24) 

tm_mday | Day of month (1-31) 

tm_mon Month (0-11; January = 0) 
tm_year Year (current year minus 1900) 
tm_wday Day of week (0—6; Sunday = 0) 
tm_yday Day of year (0-365; January 1 = 0) 
tm_isdst Always 0 for gmtime 


The gmtime, mktime, and localtime functions use a single statically allocated structure to 
hold the result. Each call to one of these routines destroys the result of any previous call. 


DOS and OS/2 do not accommodate dates prior to 1980. If timer represents a date prior to 
1980, gmtime returns NULL. 


Return Value The gmtime function returns a pointer to the structure result. There is no error return. 


Compatibility M@ ANS! @ DOS  OS/2 MH UNIX. @ XENIX 
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See Also asctime, ctime, ftime, localtime, time 


Example 


/* GMTIME.C: This program uses gmtime to convert a long-integer 

* representation of Greenwich mean time to a structure named newtime, 
* then uses asctime to convert this structure to an output string. 

xy 


##include <time.h> 
#Hinclude <stdio.h> 


void main() 
struct tm *newtime; 
long ltime; 
time( &ltime ); 
/* Obtain Greenwich mean time: */ 


newtime = gmtime( &ltime ); 
printf( “Greenwich mean time is %s\n", asctime( newtime ) ); 


Output 


Greenwich mean time is Fri Jun 16 16:37:53 1989 


_grstatus 
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Description 


Remarks 


Returns the status of the most recent graphics function call. 
#include <graph.h> 
short far _grstatus( void );. 


The _grstatus function returns the status of the most recently used graphics function. The 

_grstatus function can be used immediately following a call to a graphics routine to deter- 
mine if errors or warnings were generated. Return values less than 0 are errors, and values 
greater than 0 are warnings. 


The following manifest constants are defined in the GRAPH.H header file for use with the 
_grstatus function: 


Value Constant Meaning 

0 _GROK Success 

-1 _GRERROR Graphics error 

—2 _GRMODENOTSUPPORTED Requested video mode not supported 

-3 _GRNOTINPROPERMODE Requested routine only works in cer- 

tain video modes 

4 _GRINVALIDPARAMETER One or more parameters invalid 

—5 _GRFONTFILENOTFOUND No matching font file found 

—6 _GRINVALIDFONTFILE One or more font files invalid 

-7 _GRCORRUPTEDFONTFILE One or more font files inconsistent 

-8 _GRINSUFFICIENTMEMORY Not enough memory to allocate buff- 
er or to complete a _floodfill 
operation 

-9 = _GRINVALIDIMAGEBUFFER Image buffer data inconsistent 

1 _GRMOOUTPUT No action taken 

2 _GRCLIPPED Output was clipped to viewport 

3 _GRPARAMETERALTERED One or more input parameters was al- 


tered to be within range, or pairs of 
parameters were interchanged to be 
in the proper order 
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After a graphics call, use an if statement to compare the return value of _grstatus to 
_GROK. For example: 


if( _grstatus < _GROK ) 
/*handle graphics error*/ ; 


The functions listed below cannot cause errors, and they all set _grstatus to GROK: 


_displaycursor _gettextposition _outmem 
_getactivepage _gettextwindow _outtext 
_getgtextvector _getvideoconfig _unregisterfonts 
_gettextcolor _getvisualpage _wrapon 


See the list below for the graphics functions that affect _grstatus. The list shows error or 
warming messages that can be set by the graphics function. In addition to the error codes 
listed, all of these functions can produce the GRERROR error code. 


Function Possible _grstatus Possible _grstatus 
_ Error Codes Warning Codes 

_are functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER _GRCLIPPED 

_clearscreen _GRNOTINPROPERMODE, 
_GRINVALIDPARAMETER 

_ellipse functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 

_GRINVALIDPARAMETER, _GRCLIPPED 

_GRINSUFFICIENTMEMORY 

_getarcinfo _GRNOTINPROPERMODE 

_getcurrentposition _GRNOTINPROPERMODE 

functions 

_getfontinfo (_GRERROR only) 

_getgtextextent (_GRERROR only) 

_getgtextvector _GRPARAMETERALTERED 

_getimage _GRNOTINPROPERMODE _GRPARAMETERALTERED 

_getphyscoord _GRNOTINPROPERMODE 

_getpixel _GRNOTINPROPERMODE 

_gettextcursor _GRNOTINPROPERMODE 


_getviewcoord functions ©§ __GRNOTINPROPERMODE 


Continued on next page 
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- Function Possible _grstatus Possible _grstatus 


Error Codes Warning Codes 

_getwindowcoord _GRNOTINPROPERMODE 

_getwritemode _GRNOTINPROPERMODE 

_imagesize functions _GRNOTINPROPERMODE 

_lineto functions _GRNOTINPROPERMODE _GRNOOUTPUT, 

_GRCLIPPED 
_moveto functions _GRNOTINPROPERMODE 
_outgtext _GRNOTINPROPERMODE _GRCLIPPED, 
~GRNOOUTPUT 

_pie functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_polygon functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_putimage functions _GRERROR, _GRPARAMETERALTERED, 
_GRNOTINPROPERMODE, _GRNOOUTPUT 
_GRINVALIDPARAMETER, 
_GRINVALIDIMAGEBUFFER 

_rectangle functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_registerfonts _GRCORRUPTEDFONTFILE, 
_GRFONTFILENOTFOUND, | 
_GRINSUFFICIENTMEMORY, 

_GRINVALIDFONTFILE 

_scrolltextwindow _GRNOOUTPUT 

_selectpalette _GRNOTINPROPERMODE, 
_GRINVALIDPARAMETER 

_Setactivepage _GRINVALIDPARAMETER | 

_setbkcolor _GRINVALIDPARAMETER _GRPARAMETERALTERED 

_setcliprgn _GRNOTINPROPERMODE _GRPARAMETERALTERED 

_setcolor _GRNOTINPROPERMODE _GRPARAMETERALTERED 

setfont _GRERROR, 

2 _GRFONTFILENOTFOUND, 
_GRINSUFFICIENTMEMORY, 
_GRPARAMETERALTERED 


- Continued on next page 
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Function Possible _grstatus Possible _grstatus 

Error Codes Warning Codes 
_setgtextvector _GRPARAMETERALTERED 
_settextcolor _GRPARAMETERALTERED 
_settextcursor _GRNOTINPROPERMODE 
_Settextposition _GRPARAMETERALTERED 
_Settextrows _GRINVALIDPARAMETER _GRPARAMETERALTERED 
_Settextwindow _GRPARAMETERALTERED 
_setvideomode _GRERROR, 

_GRMODENOTSUPPORTED, 

_GRINVALIDPARAMETER 
_setvideomoderows _GRERROR, 

_GRMODENOTSUPPORTED, 

_GRINVALIDPARAMETER 
_setvieworg _GRNOTINPROPERMODE 
_setviewport _GRNOTINPROPERMODE _GRPARAMETERALTERED 
_setvisualpage _GRINVALIDPARAMETER 

setwindow _GRNOTINPROPERMODE, _GRPARAMETERALTERED 

~ _GRINVALIDPARAMETER 
_setwritemode _GRNOTINPROPERMODE, 

_GRINVALIDPARAMETER 
Return Value The _grstatus function returns the status of the most recently used graphics function. 
See Also _arce functions, ellipse functions, _floodfill, _lineto functions, _pie functions, 


_remapallpalette, _setactivepage, _setbkcolor, _setcolor, _setpixel functions, 
_settextcolor, _settextcursor, setvisualpage, _setwindow, _setwritemode 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Allocates a huge memory block. 
#include <malloc.h> Required only for function declarations 
void _huge *halloc( long num, size_t size ); 


num Number of elements 


size Length in bytes of each element 


The halloc function allocates a huge array from the operating system consisting of num ele- 
ments, each of which is size bytes long. Each element is initialized to 0. If the size of the 
array is greater than 128K (131,072 bytes), the size of an array element must then be a 
power of 2. 


The halloc function returns a void huge pointer to the allocated space, which is guaranteed 
to be suitably aligned for storage of any type of object. To get a pointer to a type other than 
void huge, use a type cast on the return value. If the request cannot be satisfied, the return 
value is NULL. 


O ANS| @ DOS Mos2 QO UNIX OC XENIX 


calloc functions, free functions, hfree, malloc functions 


/* HALLOC.C: This program uses halloc to allocate space for 38,088 long 
* jntegers, then uses hfree to deallocate the memory. 


*/ 


dhinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Finclude <malloc.h> 


void main() 


( 


long _huge *hbuf; 
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/* Allocate huge buffer */ 
hbuf = (long _huge *)halloc(: 30@@8L, sizeof( long ) ); 
if ( hbuf == NULL ) 
printf( "Insufficient memory available\n" ); 
else 
printf( "Memory successfully allocated\n" ); 


/* Free huge buffer */ 
hfree( hbuf ); 


Output 


Memory successfully allocated 
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Description 


Remarks 


Handle critical error conditions. 
#include <dos.h> 


void harderr( void(_far *handler )( )); 
void _hardresume( int result ); 


void _hardretn( int error ); 


handler () New INT 0x24 handler 
result Handler return parameter 
error Error to return from 


These three functions are used to handle critical error conditions that use DOS interrupt 
0x24. The _harderr function installs a new critical-error handler for interrupt 0x24. 


The _hardresume and _hardreturn functions control how the program will return from 
the new critical-error handler installed by harderr. The _hardresume function returns to 
DOS from a user-installed critical-error handler, and the _hardreturn function returns 
directly to the application program from a user-installed critical-error handler. 


The _harderr function does not directly install the handler pointed to by handler; instead, 
_harderr installs a handler that calls the function referenced by handler. The handler calls 
the function with the following parameters: 


handler(unsigned deverror, unsigned errcode, unsigned far *devhdr); 


The deverror argument is the device error code. It contains the AX register value passed 
by DOS to the INT 0x24 handler. The errcode argument is the DI register value that DOS 
passes to the handler. The low-order byte of errcode can be one of the following values: 


Code Meaning 


Attempt to write to a write-protected disk 
Unknown unit 


Drive not ready 


0 
1 
2 
3 Unknown command 
4 Cyclic-redundancy-check error in data 
5 


Bad drive-request structure length 
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6 Seek error 

7 Unknown media type 
8 Sector not found 

9 Printer out of paper 
10 Write fault 

11 Read fault 

12 General failure 


The devhdr argument is a far pointer to a device header that contains descriptive informa- 
tion about the device on which the error occurred. The user-defined handler must not 
change the information in the device-header control block. 


Errors on Disk Devices 


If the error occurred on a disk device, the high-order bit (bit 15) of the deverror argument 
will be set to 0, and the deverror argument will indicate the following: 


Bit Meaning 

15 Disk error if false (0). 

14 Not used. 

13 “Ignore” response not allowed if false (0). 

12 “Retry” response not allowed if false (0). 

il “Fail” response not allowed if false (0). Note that DOS 
changes “fail” to “abort”. 

10, 9 Code Location 
00 DOS 
01 File allocation table 


10 Directory 


ll Data area 


8 . Read error if false; write error if true. 
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The low-order byte of deverror indicates the drive in which the error occurred (0 = drive 
A,1= drive B, etc.). 


Errors on Other Devices 


If the error occurs on a device other than a disk drive, the high-order bit (bit 15) of the 
deverror argument is 1. The attribute word located at offset 4 in the device-header block in- 
dicates the type of device that had the error. If bit 15 of the attribute word is 0, the error is 

a bad memory image of the file allocation table. If the bit is 1, the error occurred on a char- 
acter device and bits 0-3 of the attribute word indicate the type of device, as shown in the 


following list: 

Bit Meaning 

0 Current standard input 
1 Current standard output 
2 Current null device 

3 Current clock device 


Restrictions on Handler Functions 


The user-defined handler function can issue only system calls 0x01 through 0x0C, or 
0x59. Thus, many of the standard C run-time functions (such as stream I/O and low-level 
I/O) cannot be used in a hardware error handler. Function 0x59 can be used to obtain 
further information about the error that occurred. 


Using _hardresume and _harderr 
If the handler returns, it can do so 
1. From the return statement 


2. From the _hardresume function 


3. From the _hardretn function 


If the handler returns from _hardresume or from a return statement, the handler returns 
to DOS. 
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Return Value 
Compatibility 


See Also 


The _hardresume function should be called only from within the user-defined hardware 
error-handler function. The result supplied to__hardresume must be one of the following 
constants: 


Constant Action 

_HARDERR_ABORT Abort the program by issuing INT 0x23 

_HARDERR_FAIL Fail the system call that is in progress (this is not supported on 
DOS 2.x) 


_HARDERR_IGNORE Ignore the error 
_HARDERR_RETRY Retry the operation 


The _hardretn function allows the user-defined hardware error handler to return directly 
to the application program rather than returning to DOS. The application resumes at the 
point just after the failing I/O function request. The _hardretn function should be called 
only from within a user-defined hardware error-handler function. 


The error parameter of _hardretn should be a DOS error code, as opposed to the XENIX- 
style error code that is available in errno. Refer to MS-DOS Encyclopedia (Duncan, ed.; 
Redmond, Wa.: Microsoft Press, 1988) or Programmer’ s PC Sourcebook (Hogan; Red- 
mond, Wa.: Microsoft Press, 1988) for information about the DOS error codes that may be 
returned by a given DOS function call. 


If the failing I/O function request is an INT 0x21 function greater than or equal to function 
0x38, hardretn will then return to the application with the carry flag set and the AX reg- 
ister set to the _hardretn error parameter. If the failing INT 0x21 function request is less 
than function 0x38 and the function can return an error, the AL register will be set to OXFF 
on return to the application. If the failing INT 0x21 does not have a way of returning an 
error condition (which is true of certain INT 0x21 functions below 0x38), the error param- 
eter of hardretn is not used, and no error code is returned to the application. 


None. 
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_chain_intr, _dos_getvect, _dos_setvect 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


Add memory to the heap (_heapadd) or to the based heap (_bheapadd). 
#include <malloc.h> Required only for function declarations 


int heapadd( void _far *memblock, size_t size ); 


int _bheapadd( segment seg, void _based (void) *memblock, size_t size ); 


seg Based-heap segment selector 
buffer Pointer to heap memory 
size Size in bytes of memory to add 


The _heapadd and _bheapadd functions add an unused piece of memory to the heap. The 
_bheapadd function adds the memory to the based heap specified by seg. The _heapadd 
function looks at the segment value and, if it is DGROUP, adds the memory to the near 
heap. Otherwise, heapadd adds the memory to the far heap. 


These functions return 0 if successful, or —1 if an error occurred. 
CO ANS! H& DOS WH OS/72 QO UNIX O XENIX 


free functions, halloc, hfree, malloc functions, realloc functions 


/* HEAPMIN.C: This program illustrates heap management using 
* _heapadd and _heapmin. 


=, 


dHinclude <stdio.h> 
#FHinclude <conio.h> 
#Hinclude <process.h> 
#Hinclude <malloc.h> 
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void heapdump( char *msg ); /* Prototype */ 


char sl[] = ( “Here are some strings that we use at first, then don't\n" J; 
char s2[] = { “need any more. We'll give their space to the heap.\n" }; 


void main() 
{ 
int *p{3], i; 


printf( "%s%s", sl, s2 ); 
heapdump( “Initial heap" ); 


/* Give space of used strings to heap. */ 
_heapadd( sl, sizeof( sl ) ); 

_heapadd( s2, sizeof( s2 ) ); 

heapdump( “After adding used strings" ); 


/* Allocate some blocks. Some may use string blocks from _heapadd. */ 
for( i = @; i < 2; i++ ) 
if( (pli] = (int *)calloc( 10 * (i + 1), sizeof( int ) )) == NULL ) 
{ 
--i; 
break; 
} 
heapdump( “After allocating memory" ); 


/* Free some of the blocks. */ 
free( p{l] ); 

free( pl2] ); 

heapdump( “After freeing memory" ); 


/* Minimize heap. */ 

_heapmin(); 

heapdump( "After compacting heap" ); 
} 


/* Walk through heap entries, displaying information about each block. */ 
void heapdump( char *msg ) 
{ 

struct _heapinfo hi; 


printf( “%s\n", msg ); 

hi. _pentry = NULL; 

while( _heapwalk( &hi ) == _HEAPOK ) 

printf( "“\t%s block at 4Fp of size %u\t\n", 

hi._useflag == _USEDENTRY ? "USED" : "FREE", 
hi._pentry, 
hi._size ); 

getch(); 
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Output 


Here are some strings that we use at first, then don't 
need any more. We'll give their space to the heap. 
Initial heap 
USED block at 2039:@E9C of size 364 
USED biock at 2D39:100A of size 36 
USED block at 2D39:1030 of size 512 
FREE block at 2D39:1232 of size 460 
After adding used strings 
FREE block at 2D39:0044 of size 52 
FREE block at 2D39:@07A of size 5@ 
USED block at 2039:Q@AE of size 3564 
USED block at 2039:QE9C of size 364 
USED block at 2039:1Q80A of size 36 
USED block at 2039:1938 of size 512 
FREE block at 2D39:1232 of size 460 
After allocating memory 
USED block at 2D39:@044 of size 20 
USED block at 2D39:@05A of size 40 
FREE block at 2039:0084 of size 4@ 
USED block at 2D39:Q@AE of size 3564 
USED block at 2039:@E9C of size 364 
USED block at 2039:180A of size 36 
USED block at 2D39:1030 of. size 512 
FREE block at 2D39:1232 of size 460 
After freeing memory |. 
USED block at 2039:0044 of size 20 
FREE block at 2D39:Q05A of size 40 
FREE block at 2D39:0084 of size 40 
USED block at 2D39:Q@AE of size 3564 
USED block at 2039:QE9C of size 364 
USED block at 2039:100A of size 36 
USED block at 2D39:1038 of size 512 
FREE block at 2D39:1232 of size 462 
After compacting heap 
USED block at 2D39:@044 of size 2@ 
FREE block at 2D39:905A of size 82 
USED block at 2D39:@@AE of size 3564 
USED block at 2039:@E9C of size 364 
USED block at 2D39:100A of size 36 
USED block at 2039:1030 of size 512 
FREE block at 2039:1232 of size 12 
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Description Run consistency checks on the heap. 
#include <malloc.h> 
int heapchk( void ); 
int bheapchk( segment seg ); 
int fheapchk( void ); 
int nheapchk( void ); \ 
seg Specified base heap 
Remarks The _heapchk routines help to debug heap-related problems by checking for minimal con- 
sistency of the heap. 
Each function checks a particular heap, as listed below: 
Function Heap Checked 
_heapchk Depends on data model of program 
_bheapchk Based heap specified by seg value 
_fheapchk Far heap (outside the default data segment) 
_nheapchk Near heap (inside the default data segment) 
In large data models (that is, compact-, large-, and huge-model programs), heapchk maps 
to_fheapchk. In small data models (tiny-, small-, and medium-model programs), 
_heapchk maps to _nheapchk. 
Return Value All four routines return an integer value that is one of the following manifest constants (de- 


Compatibility 


fined in MALLOC.H): 


Constant — Meaning 

_HEAPBADBEGIN Initial header information cannot be found, or it is bad 
_HEAPBADNODE Bad node has been found, or the heap is damaged 
_HEAPEMPTY | Heap has not been initialized 

_HEAPOK Heap appears to be consistent 
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ee 
See Also _heapset functions, _heapwalk functions 


Example 


/* HEAPCHK.C: This program checks the heap for consistency 
* and prints an appropriate message. 
*/ 


#finclude <malloc.h> 
#Hinclude <stdio.h> 


void main() 

{ 
int heapstatus; 
char *buffer; 


/* Allocate and deallocate some memory */ 
if( (buffer = (char *)malloc( 100 )) != NULL ) 
free( buffer ); 


/* Check heap status */ 
heapstatus = _heapchk(); 
switch( heapstatus ) 
{ 
case _HEAPOK: 
printf(" OK - heap is fine\n" ); 
break; 
case _HEAPEMPTY: 
printf(" OK - heap is empty\n" ); 
break; 
case _HEAPBADBEGIN: 
printf( "ERROR - bad start of heap\n" ); 
break; 
case _HEAPBADNODE: 
printf( "ERROR - bad node in heap\n" ); 
break; 


Output 


OK - heap is fine 


_heapmin Functions 


411 
Description Release unused heap memory to the operating system. 
#include <malloc. h> 
int heapmin( void ); 
int bheapmin( segment seg ) 
int fheapmin( void ); 
int nheapmin( void ); 
seg Specified based-heap selector 
Remarks The _heapmin functions minimize the heap by releasing unused heap memory to the oper- 


Return Value 


Compatibility 


See Also 


ating system. 


The various _heapmin functions release unused memory in these heaps: 


Function Heap Minimized 

_heapmin Depends on data model of program 

_bheapmin Based heap specified by seg value: _NULLSEG specifies all 
based heaps 

_fheapmin Far heap (outside default data segment) 

_nheapmin Near heap (inside default data segment) 


In large data models (that is, compact-, large-, and huge-model programs), heapmin 
maps to _fheapmin. In small data models (tiny-, small-, and medium-model programs), 
_heapmin maps to _nheapmin. 


Based-heap segments are never freed (i.e., unlinked from the based heap list and released 
back to the operating system) by the _bheapmin function. The _bfreeseg function is used 
for that purpose. 


The _heapmin functions return 0 if the function completed successfully, or —1 in the case 
of an error. 
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Description 


Remarks 


Check heaps for minimal consistency and set the free entries to a specified value. 
#include <malloc.h> 


int heapset( unsigned int fill ); 

int bheapset( segment seg, unsigned int fill ); 
int _fheapset( unsigned int fill ); 

int nheapset( unsigned int fill ); 


fill Fill character 


seg Specified based-heap segment selector 


The _heapset family of routines helps debug heap-related problems in programs by show- 
ing free memory locations or nodes unintentionally overwritten. 


The _heapset routines first check for minimal consistency on the heap in a manner identi- 
cal to that of the heapchk functions. After the consistency check, the _heapset functions 
set each byte of the heap’s free entries to the fill value. This known value shows which 
memory locations of the heap contain free nodes and which locations contain data that 
were unintentionally written to freed memory. 


The various _heapset functions check and fill these heaps: 


Function Heap Filled 

_heapset Depends on data model of program 

__bheapset Based heap specified by seg value, _NULLSEG specifies all 
based heaps 

_fheapset Far heap (outside default data segment) 

_nheapset Near heap (inside default data segment) 


In large data models (that is, compact-, large-, and huge-model programs), heapset maps 
to _fheapset. In small data models (tiny-, small-, and medium-model programs), _heapset 
maps to _nheapset. 
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Return Value All four routines return an int whose value is one of the following manifest constants 
(defined in MALLOC.H): 
Constant Meaning 
_HEAPBADBEGIN Initial header information cannot be found, or it is invalid 
_HEAPBADNODE Bad node has been found, or the heap is damaged 
_HEAPEMPTY Heap has not been initialized 
_HEAPOK Heap appears to be consistent 

Compatibility -O ANS! @ DOS WM OS/2 OF UNIX O XENIX 

See Also _heapchk functions, _heapwalk functions 

Example 


/* HEAPSET.C: This program checks the heap and fills in free entries 
* with the character 'Z'. 
*] 


#Hinclude <malloc.h> 
fHinclude <stdio.h> 
#Hinclude <stdlib.h> 


void main() 

{ 
int heapstatus; 
char *buffer; 
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if( (buffer = malloc( 1 )) == NULL ) /* Make sure heap is initialized */ 
exit( @ ); 
heapstatus = _heapset( 'Z' ); /* Fill in free entries */ 
switch( heapstatus ) 
{ 
case _HEAPOK: 
printf( "OK - heap is fine\n" ); 
break; 
case _HEAPEMPTY: 
printf( "OK - heap is empty\n" ); 
break; 
case _HEAPBADBEGIN: 
printf( "ERROR - bad start of heap\n" ); 
break; 
case _HEAPBADNODE: 
printf( "ERROR - bad node in heap\n" ); 
break; 
} 
free( buffer ); 


Output 


OK - heap is fine 


415 _heapwalk Functions 


Description Traverse the heap and return information about the next entry. 
include <malloc.h> 


int_heapwalk(_ HEAPINFO *entryinfo ); 
int bheapwalk( segment seg, HEAPINFO *entryinfo ); 
int fheapwalk( HEAPINFO “entryinfo ); 
int_nheapwalk( HEAPINFO *entryinfo); 


entryinfo Buffer to contain heap information 
seg Based-heap segment selector 
Remarks The _heapwalk family of routines helps debug heap-related problems in programs. 


The _heapwalk routines walk through the heap, traversing one entry per call, and return a 
pointer to a_heapinfo structure that contains information about the next heap entry. The 
; _heapinfo structure, defined in MALLOC.H, contains the following elements: 


Element Description 

int far *_pentry Heap entry pointer 
size_t _size Size of heap entry 
int _useflag Entry “in use” flag 


A call to _heapwalk that returns HEAPOK stores the size of the entry in the _ size field 
and sets the _useflag field to either_FREEENTRY or _USEDENTRY (both are constants 
defined in MALLOC.H). To obtain this information about the first entry in the heap, pass 
the _heapwalk routine a pointer to a_heapinfo structure whose _pentry field is NULL. 


The various _heapwalk functions walk through and gather information on these heaps: 


Function Heap Walked 
_heapwalk Depends on data model of program 
_bheapwalk Based heap specified by seg value; NULLSEG specifies all 
. based heaps 
* _fheapwalk Far heap (outside default data segment) 


_nheapwalk Near heap (inside default data segment) 


_heapwalk Functions 416 


In large data models (that is, compact-, large-, and huge-model programs), heapwalk 
maps to _fheapwalk. In small data models (tiny-, small-, and medium-model programs), 
_heapwalk maps to _nheapwalk. 


Return Value All three routines return one of the following manifest constants (defined in MALLOC.H): 
Constant Meaning 
_HEAPBADBEGIN The initial header information cannot be found, or it is invalid. 
_HEAPBADNODE A bad node has been found, or the heap is damaged. 
_HEAPBADPTR The _pentry field of the _heapinfo structure does not contain 

a valid pointer into the heap. 

_HEAPEND The end of the heap has been reached successfully. 
_HEAPEMPTY The heap has not been initialized. 
_HEAPOK No errors so far; the _heapinfo structure contains information 


about the next entry. 
Compatibility O ANS! @ DOS WM OS/2 O UNIX O XENIX 


See Also _heapchk functions, _heapset functions 


Example 


/* HEAPWALK.C: This program “walks” the heap, starting at the beginning 
* (_pentry = NULL). It prints out each heap entry's use, location, 

* and size. It also prints out information about the overall state 

* of the heap as soon as _heapwalk returns a value other than _HEAPOK. 
*/ 


dHinclude <stdio.h> 
#Finclude <malloc.h> 
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void heapdump( void ); 


void main() 
{ 
char *buffer; 


heapdump(); 
if( (buffer = malloc( 59 )) != NULL ) 
{ 
heapdump(); 
free( buffer ); 
} 
heapdump(); 
} 


void heapdump( void. ) 

{ 
struct _heapinfo hinfo; 
int heapstatus; 


hinfo._pentry = NULL; 
while( ( heapstatus = _heapwalk( &hinfo ) ) == _HEAPOK ) 
{ 
printf( "%6s block at 4Fp of size %4.4X\n", 
( hinfo._useflag == _USEDENTRY ? "USED" : "FREE" ), 
hinfo._pentry, hinfo._size ); 
} 


switch( heapstatus ) 
{ 
case _HEAPEMPTY: 
printf( "OK - empty heap\n" ); 
break; 
case _HEAPEND: 
printf( “OK - end of heap\n" ); 
break; 
case _HEAPBADPTR: 
printf( “ERROR - bad pointer to heap\n" ); 
break; 
case _HEAPBADBEGIN: 
printf( "ERROR - bad start of heap\n" ); 
break; 
case _HEAPBADNODE: 
printf( "ERROR - bad node in heap\n" ); 
break; 
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Output 


USED block 
USED block 
USED block 
USED block 
FREE block 


OK - end of heap 


USED block 
USED block 
USED block 
USED block 
USED block 
FREE block 


OK - end of heap 


USED block 
USED block 
USED block 
USED btock 
FREE block 
FREE block 


OK - end of heap 


at 
at 
at 
at 
at 


at 
at 
at 
at 
at 
at 


O67: 
0267: 
0067: 
0067: 
O67: 


QQ67: 
0067: 
Q067: 
0067: 
0067: 
QQ67: 


QB67: 
QQ67: 
Q067: 
QQ67: 
0067: 
QGQ67: 


193E 
104E 
1244 
126C 
146E 


103E 
194E 
1244 
126C 
146E 
14AC 


193E 
1Q4E 
1244 
126C 
146E 
14AC 


size 
size 
size 
size 
size 


size 
size 
size 
size 
size 
size 


size 
size 
size 
size 
size 
size 


OBE 
Q1F4 
0026 
8200 
B90 


OBE 
O1F4 
0826 
0200 
QBB3C 
QB52 


BOGE 
Q1F4 
0026 
0200 
QBO3C 
QB52 
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Description Frees a huge memory block. 
#include <malloc.h> Required only for function declarations 
void hfree( void huge *memblock ); 
memblock Pointer to allocated memory block 


Remarks The hfree function deallocates a memory block; the freed memory is returned to the oper- 
ating system. The memblock argument points to a memory block previously allocated 
through a call to halloc. The number of bytes freed is the number of bytes specified when 
the block was allocated. 


Note that attempting to free an invalid memblock argument (one not allocated with halloc) 
may affect subsequent allocation and cause errors. 


Return Value None. 

Compatibility O ANS! @ DOS # OS2 QO UNIX O XENIX 
See Also halloc 

Example 


/* HALLOC.C: This program uses halloc to allocate space for 38,088 long 
* integers, then uses hfree to deallocate the memory. 
soit 


#Hinclude <stdio.h> 
dHinclude <stdlib.h> 
dFinclude <malloc.h> 


void main() 
{ 
long _huge *hbuf; 


/* Allocate huge buffer */ 
hbuf = (long _huge *)halloc( 30@@8L, sizeof( long ) ); 
if ( hbuf == NULL ) 
printf( “Insufficient memory available\n" ); 
else 
printf( “Memory successfully allocated\n" ); 
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/* Free huge buffer */ 
hfree( hbuf ); 


Output 


Memory successfully allocated 
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hypot, hypotl 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Calculate the hypotenuse. 
#include <math.h> 


double hypot( double x, double y ); 
long double hypotl( long double x, long double y ); 


x,y Floating-point values 


The hypot and hypotl functions calculate the length of the hypotenuse of a right triangle, 
given the length of the two sides x and y (or x/ and y/). A call to hypot is equivalent to the 
following: 


sqrt(x+#x+y*y); 


The hypotl function uses the 80-bit, 10-byte coprocessor form of arguments and return 
values. See the reference page on the long double functions for more details on this data 


type. 


The functions return the length of the hypotenuse. If an overflow results, the functions re- 
turn HUGE_VAL and set errno to ERANGE. 


hypot 
O ANS! @ DOS # OS/2 UNIX’ Wf XENIX 
hypotl 


O ANS! @ DOS MM OSf O UNIX O XENIX 


cabs 


/* HYPOT.C: This program prints the hypotenuse of a right triangle. */ 


fHinclude <math.h> 
#Hinclude <stdio.h> 
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void main() 
( 
double x = 3.0, y = 4.0; 


printf( “If a right triangle has sides %2.1f and %2.1f, " 
"its hypotenuse is %2.1f\n", x, y, hypot( x, y ) ); 


Output 


If a right triangle has sides 3.8 and 4.0, its hypotenuse is 5.8 


423 _imagesize Functions 
Description Get amount of memory required to store graphics images. 

#include <graph.h> 

long far imagesize( short x/, short y/, short x2, short y2 ); 

long far _imagesize_w( double wx/, double wy/, double wx2, double wy2 ); 

long far _imagesize_wxy( struct _wxycoord far *pwxyl, 

struct wxycoord _far *pwxy2 ); 

xl, yl Upper-left corner of bounding rectangle 

x2, y2 Lower-right corner of bounding rectangle 

wxl, wyl Upper-left corner of bounding rectangle 

wx2, wy2 Lower-right comer of bounding rectangle 

pwxyl Upper-left corner of bounding rectangle 

pwxy2 Lower-right corner of bounding rectangle 
Remarks The functions in the _imagesize family return the number of bytes needed to store the 


Return Value 


Compatibility 


image defined by the bounding rectangle and specified by the coordinates given in the 
function call. 


The _imagesize function defines the bounding rectangle in terms of view-coordinate 
points (x/, yl) and (x2, y2). 


The -imagesize_w function defines the bounding rectangle in terms of window-coordinate 
points (x/, yl) and (x2, y2). 


The _imagesize_wxy function defines the bounding rectangle in terms of the window- 
coordinate pairs pwxyl and pwxy2. 


The number of bytes needed to store the image is determined by the following formula: 


xwid = abs(x1-x2)+1; 
ywid = abs(yl-y2)+1; 
size = 4+( (long) ((xwid*bits_per_pixel+7)/8)*(long) ywid); 


A call to _getvideoconfig stores the bits_per_pixel information in the bitsperpixel 
field of a videoconfig structure. 


The function returns the storage size of the image in bytes. There is no error return. 


O ANS! @ DOS OF OS OF UNIX OF XENIX 
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See Also _getimage functions, _getvideoconfig, _putimage functions 


Example See the example for _getimage. 


425 inp, inpw 
Description Input a byte (inp) or a word (inpw) from a port. 

#include <conio.h> Required only for function declarations 

int inp( unsigned port ); 

unsigned inpw( unsigned port ); 

port Port number 
Remarks The inp and inpw functions read a byte and a re respectively, from the specified input 


Return Value 


Compatibility 


See Also 


Example 


port. The input value can be any unsigned integer in the range 0 — 65,535. 


To use inp and inpw in OS/2 protected mode, you must use a .DEF file to declare the 
IOSEG segment that the run-time library uses to perform input/output on the port. In addi- 
tion, the intrinsic (/Oi) versions of these functions do not work unless you put the code in a 


. Segment that is marked with the IOPL keyword in the .DEF file. 


Because you cannot do IOPL from a regular code segment, the run-time library 
declares a separate code segment called IOSEG. In order to use inp, inpw, outp, 

or outpw in any of the protected-mode run-time libraries (7LIBCP, LLIBCDLL, 
LLIBCMT, or CDLLOBJS-based DLL), you must have a .DEF file containing this line: 


SEGMENTS _IOSEG CLASS 'IOSEG_CODE' IOPL 

The functions return the byte or word read from port. There is no error return. 
O ANS! #@ DOS WM OS2 0 UNIX OO XENIX 

outp, outpw 


See the example for outp. 


int86 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Executes the 8086 interrupt. 
#include <dos.h> 


int int86( int intnum, union REGS *inregs, union REGS *outregs ); 


intnum Interrupt number 
inregs Register values on call 
outregs Register values on return 


The int86 function executes the 8086-processor-family interrupt specified by the interrupt 
number intnum. Before executing the interrupt, int86 copies the contents of inregs to the 
corresponding registers. After the interrupt returns, the function copies the current register 
values to outregs. It also copies the status of the system carry flag to the cflag field in the 
outregs argument. The inregs and outregs arguments are unions of type REGS. The union 
type is defined in the include file DOS.H. 


Do not use the int86 function to call interrupts that modify the DS register. Instead, use the 
int86x function. The int86x function loads the DS and ES registers from the segregs para- 
meter and also stores the DS and ES registers into segregs after the function call. 


The REGS type is defined in the include file DOS.H. 


The return value is the value in the AX register after the interrupt returns. If the cflag field 
in outregs is nonzero, an error has occurred; in such cases, the _doserrno variable is also 
set to the corresponding error code. 


O ANS! @ DOS OF OS/ O UNIX O XENIX 


bdos, int86x, intdos, intdosx 


/* INT86.C: This program uses int86 to call the BIOS video service 
* (INT 18H) to get information about the cursor. 


A 


#Hinclude <dos.h> 
#Hinclude <stdio.h> 
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void main() 


( 
union REGS inregs, outregs; 


/* Set up to get cursor information, */ 
inregs.h.ah = 3; /* Get Cursor Position function */ 
inregs.h.bh = Q; /* Page @ */ 


/* Execute video interrupt: */ 
int86( @x1@, &inregs, &outregs ); 


/* Display results. */ 

printf( “Cursor position\n\tRow: %d\n\tColumn: %d\n", 
outregs.h.dh, outregs.h.dl ); 

printf( "Cursor shape\n\tStart: %d\n\tEnd: %d\n", 
outregs.h.ch, outregs.h.cl ); 


Output 


Cursor position 
Row: 2 
Column: @ 

Cursor shape 
Start: 6 
End: 7 
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Description Executes the 8086 interrupt; accepts segment-register values. 
#include <dos.h> 


int int86x( int intnum, union REGS *inregs, union REGS *outregs, 
struct SREGS *segregs ); 


intnum Interrupt number 
inregs Register values on call 
outregs Register values on return 
segregs Segment-register values on call 
Remarks — The int86x function executes the 8086-processor-family interrupt specified by the inter- 


rupt number intnum. Unlike the int86 function, int86x accepts segment-register values in 
segregs, enabling programs that use large-model data segments or far pointers to specify 
which segment or pointer should be used during the system call. 


Before executing the specified interrupt, int86x copies the contents of inregs and segregs 
to the corresponding registers. Only the DS and ES register values in segregs are used. 
After the interrupt returns, the function copies the current register values to outregs, cop- 
ies the current ES and DS values to segregs, and restores DS. It also copies the status of 
the system carry flag to the cflag field in outregs. 


The REGS and SREGS types are defined in the include file DOS.H. 
Segment values for the segregs argument can be obtained by using either the segread func- 


tion or the FP_SEG macro. 


Return Value The return value is the value in the AX register after the interrupt returns. If the cflag field 
in outregs is nonzero, an error has occurred; in such cases, the _doserrno variable is also 
set to the corresponding error code. 


Compatibility QO} ANS! @ DOS OF 0S/72 QO UNIX O XENIX 


See Also bdos, FP_SEG, int86, intdos, intdosx, segread 
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Example 


/* INT86X.C: In this program, int86x executes an INT 21H instruction 

to invoke DOS system call 43H (change file attributes). The program 
uses int86x because the file, which is referenced with a far pointer, 
may be in a segment other than the default data segment. Thus, the 

* program must explicitly set the DS register with the SREGS structure. 
ad 


+ + OF 


#Hinclude <signal.h> 
#tinclude <dos.h> 
fFinclude <stdio.h> 
#tinclude <process.h> 


char _far *filename = "int86x.c"; 


void main() 

{ 
union REGS-inregs, outregs; 
struct SREGS segregs; 
int result; 


inregs.h.ah = @x43; /* DOS function to change attributes * / 
inregs.h.al Q; /* Subfunction @ to get attributes) */ 
inregs.x.dx = FP_OFF( filename ); /* DS:DX points to file name */ 
segregs.ds = FP_SEG( filename ); 
result = int86x( @Ox2l, &inregs, &outregs, &Segregs ); 
if( outregs.x.cflag ) 

printf( "Can't get file attributes; error no. %d\n", result); 
else 

printf( "“Attribs = O@x%.4x\n", outregs.x.cx ); 


Output 


Attribs = 9x@020 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Executes the DOS system call. 
#include <dos.h> 
int intdos( union REGS *inregs, union REGS *“outregs ); 


inregs Register values on call 


outregs Register values on return 


The intdos function invokes the DOS system call specified by register values defined in 
inregs and returns the effect of the system call in outregs. The inregs and outregs argu- 
ments are unions of type REGS. The REGS type is defined in the include file DOS.H. 


To invoke a system call, intdos executes an INT 21H instruction. Before executing the in- 
struction, the function copies the contents of inregs to the corresponding registers. After 
the INT instruction returns, intdos copies the current register values to outregs. It also cop- 
ies the status of the system carry flag to the cflag field in outregs. A nonzero cflag field in- 
dicates the flag was set by the system call and also indicates an error condition. 


The intdos function is used to invoke DOS system calls that take arguments for input or 
output in registers other than DX (DH/DL) and AL. The intdos function is also used to in- 
voke system calls that indicate errors by setting the carry flag. Under any other conditions, 
the bdos function can be used. 


Do not use the intdos function to call interrupts that modify the DS register. Instead, use 
the intdosx or int86x function. 


The intdos function returns the value of the AX register after the system call is completed. 
If the cflag field in outregs is nonzero, an error has occurred and _doserrno is also set to 
the corresponding error code. 


O ANSI @ DOS O os7 OO UNIX O XENIX 


bdos, intdosx 


/* INTDOS.C: This program uses intdos to invoke DOS system call 2AH 
* (gets the current date). 


ne 


#Hinclude <dos.h> 
dHinclude <stdio.h> 
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void main() 
{ 


union REGS inregs, outregs; 

inregs.h.ah = @x2a; * 7/* DOS Get Date function: */ 

intdos( &inregs, &outregs ); 

printf( “Date: %d/%4d/%4d\n", outregs.h.dh, outregs.h.dl, outregs.x.cx ); 
} 
Output 


Date: 6/16/1989 


intdosx 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
/* INTDOSX.C */ 


Executes the DOS system call; accepts segment-register values. 
#include <dos.h> 


int intdosx( union REGS *inregs, union REGS *outregs, struct SREGS *segregs );_ . 


inregs Register values on call 
outregs Register values on return 
segregs Segment-register values on call 


The intdosx function invokes the DOS system call specified by register values defined in 
inregs and returns the results of the system call in outregs. Unlike the intdos function, 
intdosx accepts segment-register values in segregs, enabling programs that use large- 
model data segments or far pointers to specify which segment or pointer should be used 
during the system call. The REGS and SREGS types are defined in the include file DOS.H. 


To invoke a system call, intdosx executes an INT 21H instruction. Before executing the in- 
struction, the function copies the contents of inregs and segregs to the corresponding regis- 
ters. Only the DS and ES register values in segregs are used. After the INT instruction 
returns, intdosx copies the current register values to outregs and restores DS. It also copies 
the status of the system carry flag to the cflag field in outregs. A nonzero cflag field indi- 
cates the flag was set by the system call and also indicates an error condition. 


The intdosx function is used to invoke DOS system calls that take an argument in the ES 
register or that take a DS register value different from the default data segment. 


Segment values for the segregs argument can be obtained by using either the segread func- 
tion or the FP_SEG macro. 


The intdosx function returns the value of the AX register after the system call is com- 
pleted. If the cflag field in outregs is nonzero, an error has occurred; in such cases, 
_doserrno is also set to the corresponding error code. 
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bdos, FP_SEG, intdos, segread 


d##include <dos.h> 
#include <stdio.h> 
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char _far *buffer = “Dollar-sign terminated string\n\r\n\r$"; 


void main() 

{ 
union REGS inregs, outregs; 
struct SREGS segregs; 


/* Print a $-terminated string on the screen using DOS function @x@9. */ 
inregs.h.ah Qx9; 

inregs.x.dx FP_OFF( buffer ); 

segregs.ds FP_SEG( buffer ); 

intdosx( &inregs, &outregs, &segregs ); 


Output 


Dollar-sign terminated string 


is Functions 
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Description 


Remarks 


Test characters for specified conditions. 
#include <ctype.h> 


int isalnum( int c ); 
int isalpha( int c ); 
int isascii( int c ); 
int iscntrl( int c ); 
int isdigit( int c ); 
int isgraph( int c ); 
int islower( int c ); 
int isprint( int c ); 
int ispunct( int c ); 
int isspace( int c ); 
int isupper‘( int c ); 


int isxdigit( int c ); 


c Integer to be tested 


Each function in the is family tests a given integer value, returning a nonzero value if the 
integer satisfies the test condition and 0 if it does not. The ASCII character set is assumed. 


The is functions and their test conditions are listed below: 


Function Test Condition 

isalnum Alphanumeric (’A’—’Z’, ’a’—’z’, or 
isalpha Letter (’A’—’Z’ or ’a’—’z’) 

isascii ASCII character (0x00 — 0x7F) 

iscntrl Control character (0x00 — 0x1F or 0x7F) 
isdigit Digit (0’—’9’) 

isgraph Printable character except space (’ ’) 


islower Lowercase letter (’a’—’z’) 
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is Functions 


Return Value 


Compatibility 


See Also 


Example 


isprint Printable character (0x20 — 0x7E) 

ispunct Punctuation character 

isspace White-space character (0x09 — OxOD or 0x20) | 
isupper Uppercase letter ? A’—’Z’) 

isxdigit Hexadecimal digit (’ A’—’F’,’a’-’f’, or ’0’—’9’) 


The isascii routine produces meaningful results for all integer values. However, the remain- 
ing routines produce a defined result only for integer values corresponding to the ASCII 
character set (that is, only where isascii holds true) or for the non-ASCII value EOF (de- 
fined in STDIO.H). , 


These routines are implemented both as functions and as macros. For details on choosing a 
function or a macro implementation, see Section 1.4, “Choosing ‘Between Functions and 
Macros.” 


These routines return a nonzero value if the integer satisfies the test condition and 0 if it 
does not. 


isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, 
isxdigit 


MANS! @ DOS #8 OS/2 @ UNIX Wt XENIX 
isascii 
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toascii, tolower, toupper functions 


/* ISFAM.C: This program tests all characters between @x@ and Ox7F, 
* then displays each character with abbreviations for the character-type 
* codes that apply. 


4 


fHinclude <stdio.h> 
#Hinclude <ctype.h> 
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void main() 
{ 
int ch; 
for( ch = @; ch <= Ox7F; cht+ ) 
{ ; 
printer “s.2x "ch. ds 


printf( " 2c", isprint( ch ) ? ch NO 28 
printf( "24s", isalnum( ch ) ? "AN" : "" )¢ 
printf( "%3s", isalpha( ch ) 2? “A" : "" )s 
printf( "23s", isascii( ch ) ? "AS" : "" )¢ 
DPINtTt. *2aS" 5 TVSCNERKC ‘Eh 2 7C™ ce PE Qe 
printf( "43s", isdigit( ch ) ? "D" : "" ); 
printf( "43s", isgraph( ch ) ? "G" : "" ); 
printf( "43s", islower( ch ) ? "L" : "" ); 
printf( "43s", ispunct( ch ) ? "PU" : "" ); 
printf( "%3s", isspace( ch ) ? "S" : "" ); 
printf( "23s", isprint( ch ) ? "PR® : "" ); 
printf( "43s", isupper( ch ) ? "U" : "" )3 
printf( "43s", isxdigit( ch ) ? "X" 3: "" ); 
printf( "\n" ); 
} 

} 

Output 

QO AS C 

G1 AS C 

B2 AS C 

38 8 AN AS DG PR X 

39 9 AN AS DG PR X 

3a: AS G PU PR 

3b 3: AS G PU PR 

3c << AS G PU PR 

3d = AS G PU PR 

3e > AS G PU PR 

3f 2? AS G PU PR 

49 @ AS G PU PR 

41 A AN A AS G PR U xX 

B AN A AS G PR U xX 
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Description Checks for a character device.. 
#include <io.h> Required only for function declarations 
int isatty( int handle ); 
handle Handle referring to device to be tested 


Remarks The isatty function determines whether handle is associated with a character device (a ter- 
minal, console, printer, or serial port). 


Return Value The isatty function returns a nonzero value if the device is a character device. Otherwise, 
the return value is 0. 


Compatibility O ANS! @ DOS WM OS/2 MW UNIX’ Wf XENIX 


Example 


/* ISATTY.C: This program checks to see whether stdout has been 
* redirected to a file. 
*/ 


dHinclude <stdio.h> 
#Hinclude <io.h> 


void main() 
{ 
if( isatty( fileno( stdout ) ) ) 
printf( "stdout has not been redirected to a file\n" ); 
else 
printf( "stdout has been redirected to a file\n"); 


Output 


stdout has not been redirected to a file 


itoa 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Converts an integer to a string. 
#include <stdlib.h> Required only for function declarations 


char *itoa( int value, char *string, int radix ); 


value Number to be converted 
string String result 
radix Base of value 


The itoa function converts the digits of the given value argument to a null-terminated char- 
acter string and stores the result (up to 17 bytes) in string. The radix argument specifies the 
base of value; it must be in the range 2-36. If radix equals 10 and value is negative, the 
first character of the stored string is the minus sign (—). 


The itoa function returns a pointer to string. There is no error return. 
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Itoa, ultoa 


/* ITOA.C: This program converts integers of various sizes to strings 
* in various radixes. 


a 


dhinclude <stdlib.h> 
dHinclude <stdio.h> 


void main() 


( 


char buffer[2@]; 
int i = 3445; 


tong 1 = 


~344115L; 


unsigned long ul = 123456789QUL; 
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itoa( i, buffer, 10 ); 

printf( "String of integer 4d (radix 10): %s\n", i, buffer ); 
itoa( i, buffer, 16 ); 

printf( “String of integer %d (radix 16): @x%s\n", i, buffer ); 
itoa( i, buffer, 2 ); 

printf( “String of integer %d (radix 2): %s\n", i, buffer ); 


ltoa( 1, buffer, 16 ); 
printf( “String of long int 41d (radix 16): O@x%s\n", 1, buffer ); 


ultoa( ul, buffer, 16 ); 
printf( "String of unsigned long %lu (radix 16): @x%s\n", ul, buffer ); 


Output 


String of integer 3445 (radix 10): 3445 

String of integer 3445 (radix 16): @xd75 

String of integer 3445 (radix 2): 110101110101 

String of long int -344115 (radix 16): Oxfffabfcd 

String of unsigned long 1234567898 (radix 16): @x499682d2 
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Description Checks the console for keyboard input. 

#include <conio.h> Required only for function declarations 

int kbhit( void ); 


Remarks The kbhit function checks the console for a recent keystroke. If the function returns a non- 
zero value, a keystroke is waiting in the buffer. The program can then call getch or getche 
to get the keystroke. 


Return Value The kbhit function returns a nonzero value if a key has been pressed. Otherwise, it re- 
turns 0. 


Compatibility CO ANS| @ DOS WM OS/2 O UNIX O XENIX 


Example 


/* KBHIT.C: This program loops until the user presses a key. 

* If kbhit returns nonzero, a keystroke is waiting in the buffer. 
* The program can call getch or getche to get the keystroke. 

*/ 


fHinclude <conio.h> 
#include <stdio.h> 


void main() 
{ : 
/* Display message until key is pressed. */ 
while( !kbhit() ) 
cputs( "Hit me!! " ); 


/* Use getch to throw key away. */ 


printf( "\nKey struck was ‘%c'\n", getch() ); 
getch(); 


Output 


Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! 
Key struck was ‘k' 
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Description Calculates the absolute value of a long integer. 


#include <stdlib.h> Required only for function declarations 


#include <math.h> 


long labs( long 7 ); 
n Long-integer value 
Remarks The labs function produces the absolute value of its long-integer argument n. 
Return Value The labs function returns the absolute value of its argument. There is no error return. 


Compatibility MANS! M@ DOS M OS O UNIX O XENIX 


See Also abs, cabs, fabs 


Example 


/* ABS.C: This program computes and displays the absolute values of 
* several numbers. 
af 


#Hinclude <stdio.h> 
#Hinclude <math.h> 
#Hinclude <stdlib.h> 


void main() 

{ 
int ix = -4, iy; 
long 1x = -41567L, ly; 
double dx = -3.141593, dy; 


iy = abs( ix ); 
printf( "The absolute value of 4d is %@d\n", ix, iy); 


ly = labs( 1x ); 
printf( "The absolute value of ld is %ld\n", 1x, ly); 


dy = fabs( dx ); 
printf( "The absolute value of 4f is %f\n", dx, dy ); 


labs : 442 


Output 


The absolute value of -4 is 4 
The absolute value of -41567 is 41567 
The absolute value of -3.141593 is 3.141593 


443 | Idexp, Idexpl 


Description Compute a real number from the mantissa and exponent. 
#include <math.h> 


double Idexp( double x, int exp ); 
long double Idexpl( long double x, int exp ); 


a Floating-point value 
exp Integer exponent 
Remarks The Idexp and Idexpl functions calculate the value of x * 2°”. 
Return Value The Idexp and Idexpl functions return x * 2°?. If an overflow results, the functions return 


+ HUGE_VAL (depending on the sign of x) and set errno to ERANGE. 


The Idexpl function uses the 80-bit, 10-byte coprocessor form of arguments and return 
values. See the reference page on the long double functions for more details on this data 


type. 
Compatibility Idexp 
MANS! @ DOS 8 OS/2 WUNIX' = XENIX 


Idexp! 
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See Also frexp, modf 


Example 


/* LDEXP.C */ 
fHinclude <math.h> 
#Hinclude <stdio.h> 


Idexp, Idexpl a 


void main() 


{ 
double x = 4.0, y; 
int p = 3; 


y = ldexp( x, p ); 


printf( "%2.1f times two to the power of %d is %2.1f\n", x, p, y )3 
} 


Output 


4.8 times two to the power of 3 is 32.0 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Idiv 


Computes the quotient and remainder of a long integer. 
#include <stdlib.h> 
Idiv_t Idiv ( long int numer, long int denom ); 


numer Numerator 


denom Denominator 


The Idiv function divides numer by denom, computing the quotient and the remainder. The 
sign of the quotient is the same as that of the mathematical quotient. Its absolute value is 
the largest integer that is less than the absolute value of the mathematical quotient. If the 
denominator is 0, the program will terminate with an error message. 


The Idiv function is similar to the div function, with the difference being that the argu- 
ments and the members of the returned structure are all of type long int. 


The Idiv_t structure, defined in STDLIB.H, contains the following elements: 


Element Description 
long int quot Quotient 
long int rem Remainder 


The Idiv function returns a structure of type Idiv_t, comprising both the quotient and the 
remainder. 


MANS! M@ DOS MOS O UNIX O XENIX 


div 


/* LDIV.C: This program takes two long integers as command-line 
* arguments and displays the results of the integer division. 


i] 


#Hinclude <stdlib.h> 
#Hinclude <math.h> 
d#Hinclude <stdio.h> 
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void main() 

{ 
long x = 5149627, y = 234879; 
ldiv_t div_result; 


div_result = ldiv( x, y ); 


printf( "For 41d / %1d, the quotient is %1ld, and the remainder is %1d\n", 
x, y, div_result.quot, div_result.rem ); 


Output 


For 5149627 / 234879, the quotient is 21, and the remainder is 217168 
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Description Performs a linear search for the specified key. 
#include <search.h> Required only for function declarations 


char *Ifind( const void *key, const void *base, unsigned int *num, unsigned int width, 
int ( *compare )( const void *elem/, const void *elem2 ) ); 


key Object to search for 

base Pointer to base of search data 

num Number of array elements 

width Width of array elements 

compare() Pointer to comparison routine 

eleml Pointer to the key for the search 

elem2 Pointer to the array element to be compared with the key 
Remarks The Ifind function performs a linear search for the value key in an array of num elements; 


each element is width bytes in size. (Unlike bsearch, Ifind does not require the array to be 
sorted.) The base argument is a pointer to the base of the array to be searched. 


The compare argument is a pointer to a user-supplied routine that compares two array ele- 
ments and then returns a value specifying their relationship. The Ifind function calls the 
compare routine one or more times during the search, passing pointers to two array ele- 
ments on each call. This routine must compare the elements, then return one of the follow- 


ing values: 
Value Meaning 
Nonzero Elements are different 
0 Elements are identical 
Return Value If the key is found, Ifind returns a pointer to the element of the array at base that matches _ 


key. If the key is not found, Ifind returns NULL. 


Compatibility O ANS! @ DOS MH OS/2 = UNIX” MB XENIX 
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FT Ege] 
See Also bsearch, Isearch, qsort 


Example 


/* LFIND.C: This program uses lfind to search for the word "hello" 
* in the command-line arguments. 
*/ 


dHinclude <search.h> 
#include <string.h> 
dHinclude <stdio.h> 


int compare( char **argl, char **arg2 ); 


void main( int argc, char **argv ) 
{ 

char **result; 

char *key = "hello"; 


result = (char **)1lfind( (char *)&key, (char *)argv, 
&’argc, sizeof( char * ), compare ); 
if( result ) 
printf( "%s found\n", *result ); 
else 
printf( "hello not found!\n" ); 
} , 


int compare(char ** argl, char **arg2 ) 

{ : 
return( strcempi( *argl, *arg2 ) ); 

} 


Output 


{C:\LIBREF] lfind What if I said Hello world 
Hello found 


449 


_lineto Functions 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Draw lines to specified points. 
#include <graph.h> 


short _far _lineto( short x, short y ); 


short _far _lineto_w( double wx, double wy ); 


x,y End point 

wx, Wy End point 

The functions in the _lineto family draw a line from the current graphics position up to 
and including the destination point. The destination point for the _lineto function is given 


by the view-coordinate point (x, y). The destination point for the _lineto_w function is 
given by the window-coordinate point (wx, wy). 


The line is drawn using the current color, logical write mode, and line style. If no error 
occurs, _lineto sets the current graphics position to the view-coordinate point (x, y); 
_lineto_w sets the current position to the window-coordinate point (wx, wy). 


If you use _floodfill to fill in a closed figure drawn with _lineto calls, the figure must be 
drawn with a solid line-style pattern. 


The _lineto and _lineto_w routines return a nonzero value if anything is drawn; otherwise, 
they return 0. 
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_getcurrentposition functions, _moveto functions, _setlinestyle 


/* MOVETO.C: This program draws line segments of different colors. */ 


#Hinclude <graph.h> 
dHinclude <stdlib.h> 
fHinclude <conio.h> 
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void main() 

{ 
short x, y, xinc, yinc, color = 1; 
struct videoconfig v; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1); 

_getvideoconfig( &v ); 

xinc = v.numxpixels / 5@; 

yinc = v.numypixels / 58; 


for( x = @, y = v.numypixels - 1; x < v.numxpixels; x += xinc, y -= yinc ) 
( 
_setcolor( color++ % 16 ); 
_moveto( x, @ ); 
_lineto( @, y ); 
} 
getch(); 


_setvideomode( _DEFAULTMODE ); 
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aa I a 
Description Gets detailed information on locale settings. 
#include <locale.h> 
struct Iconv “localeconv( void ); 


Remarks The localeconv function gets detailed information on the locale-specific settings for 
numeric formatting of the program’s current locale. This information is stored in a struc- 
ture of type Iconv. 


The Iconv structure, defined in LOCALE.H, contains the following elements: 


Element Description 

char *decimal_point Decimal-point character for nonmonetary 
quantities. 

char *thousands_sep Character used to separate groups of digits 


to the left of the decimal point for non- 
monetary quantities. 


char *grouping : Size of each group of digits in non- 
monetary quantities. 


char *int_curr_symbol International currency symbol for the cur- 
rent locale. The first three characters 
specify the alphabetic international cur- 
rency symbol as defined in the JSO 4217 
Codes for the Representation of Currency 
and Funds standard. The fourth character 
(immediately preceding the null character) 
is used to separate the international cur- 
rency symbol from the monetary quantity. 


char *currency_symbol Local currency symbol for the current 
locale. 

char *mon_decimal_point Decimal-point character for monetary 
quantities. 

char *mon_thousands_sep Separator for groups of digits to the left of 
the decimal place in monetary quantities. 

char *mon_grouping Size of each group of digits in monetary 
quantities. 

char *positive_sign String denoting sign for nonnegative 


monetary quantities. 


localeconv 
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_ char *negative_sign 


char int_frac_digits 
char frac_digits 


char p_cs_precedes 


char p_sep_by_space 


char n_cs_precedes 


char n_sep_by_space 


char p_sign_posn 


char n_sign_posn 


String denoting sign for negative monetary 
quantities. 


Number of digits to the right of the deci- 
mal point in internationally formatted 
monetary quantities. 


Number of digits to the right of the deci- 
mal point in formatted monetary 
quantities. 


Set to 1 if the currency symbol precedes 
the value for a nonnegative formatted 
monetary quantity. Set to 0 if the symbol 
follows the value. 


Set to 1 if the currency symbol is sepa- 
rated by a space from the value for a non- 
negative formatted monetary quantity. Set 
to 0 if there is no space separation. 


Set to | if the currency symbol precedes 
the value for a negative formatted 
monetary quantity. Set to 0 if the symbol 
succeeds the value. 


Set to 1 if the currency symbol is sepa- 
rated by a space from the value for a nega- 
tive formatted monetary quantity. Set to 0 
if there is no space separation. 


Position of positive sign in nonnegative 
formatted monetary quantities. 


Position of positive sign in negative for- 
matted monetary quantities. 
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localeconv 


Return Value 


Compatibility 


See Also 


The elements of grouping and mon_grouping are interpreted according to the following 
rules: 


Value Interpretation 
CHAR_MAX No further grouping is to be performed. 
0 The previous element is to be repeatedly used for the re- 


- mainder of the digits. 


n The integer value n is the number of digits that make up the 
current group. The next element is examined to determine the 
size of the next group of digits before the current group. 


The values for p_sign_posn and n_sign_posn are interpreted according to the following 
rules: 


Value Interpretation 

0 Parentheses surround the quantity and currency symbol 
1 Sign string precedes the quantity and currency symbol 
2 Sign string follows the quantity and currency symbol 

3 Sign string immediately precedes the currency symbol 
4 Sign string immediately follows the currency symbol 


The localeconv function returns a pointer to a structure of leonv type. Calls to the 
setlocale function with category values of LC_ALL, LC_MONETARY, or 
LC_NUMERIC will overwrite the contents of the structure. 
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setlocale, strcoll, strftime, strxfrm 


localtime 
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Description 


Remarks 


Converts a time value and corrects for the local time zone. 
#include <time.h> 

struct tm *localtime( const time_t *timer ); 

timer _ Pointer to stored time 


The localtime function converts a time stored as a time_t value and stores the result in a 
structure of type tm. The long value timer represents the seconds elapsed since 00:00:00, 
January 1, 1970, Greenwich mean time; this value is usually obtained from the time 
function. 


The fields of the structure type tm store the following values: 


Element Value Stored 

int tm_sec Seconds 

int tm_min | Minutes 

int tm_hour Hours (0-24) 

int tm_mday Day of month (1-31) 

int tm_mon Month (0-11; January = 0) 

int tm_year Year (current year minus 1900) 

int tm_wday Day of week (0O—6; Sunday = 0) 

int tm_yday ' Day of year (0-365; January 1 = 0) 

int tm_isdst Nonzero if daylight saving time is in effect, otherwise 0 


Note that the gmtime, mktime, and localtime functions use a single statically allocated 
tm structure for the conversion. Each call to one of these routines destroys the result of the 
previous call. 


The localtime function makes corrections for the local time zone if the user first sets the 
environment variable TZ. When TZ is set, three other environment variables (timezone, 
daylight, and tzname) are automatically set as well. See tzset for a description of these 

variables. 


The TZ variable is not part of the ANSI standard definition of localtime but is a Microsoft 
extension. 
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Return Value The localtime function returns a pointer to the structure result. DOS and OS/2 do not ac- 
commodate dates prior to 1980. If the value in timer represents a date prior to January 1, 
1980, the function returns NULL. 


Compatibility BANS! @ DOS #8 OS/2 WF UNIX WB XENIX 
See Also asctime, ctime, ftime, gmtime, time, tzset 
Example 


/* LOCALTIM.C: This program uses time to get the current time and 

* then uses localtime to convert this time to a structure representing 
* the local time. The program converts the result from a 24-hour clock 
* to a 12-hour clock and determines the proper extension (AM or PM). 
ey 


#Finclude <stdio.h> 
#Hinclude <string.h> 
d#Finclude <time.h> 


void main() 

{ 
struct tm *newtime; 
char am_pm[] = "AM"; 
time_t long_time; 


time( &long_time ); /* Get time as long integer. */ 
newtime = localtime( &long_time ); /* Convert to local time. */ 


if( newtime->tm_hour < 12 ) /* Set up extension. */ 
strcpy( am_pm, "AM" ); 

if( newtime->tm_hour > 12 ) /* Convert from 24-hour */ 
newtime->tm_hour -=12; /* to 12-hour clock. */ 


printf( "%.19s %s\n", asctime( newtime ), am_pm ); 


Output 


Fri Jun 16 96:27:02 AM 


locking 
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Description 


Remarks 


Locks or unlocks bytes of a file. 


#include <sys\locking.h> 


#include <io.h> Required only for function declarations 


int locking( int handle, int mode, long nbytes ); 


handle File handle 
mode File-locking mode 
nbytes Number of bytes to lock 


The locking function locks or unlocks nbytes bytes of the file specified by handle. Lock- 
ing bytes in a file prevents access to those bytes by other processes. All locking or unlock- 
ing begins at the current position of the file pointer and proceeds for the next nbytes bytes. 
It is possible to lock bytes past the end of the file. 


The mode argument specifies the locking action to be performed. It must be one of the fol- 
lowing manifest constants: 


Constant Action 


LK_LOCK Locks the specified bytes. If the bytes cannot be locked, imme- 
diately tries again after 1 second. If, after 10 attempts, the 
bytes cannot be locked, returns an error. 


LK_NBLCK Locks the specified bytes. If bytes cannot be locked, returns 
an error. 

LK_NBRLCK Same as LK_NBLCK. 

LK_RLCK Same as LK_LOCK. 

LK_UNLCK Unlocks the specified bytes. (The bytes must have been pre- 
viously locked.) 


More than one region of a file can be locked, but no overlapping regions are allowed. 


When a region of a file is being unlocked, it must correspond to a region that was pre- 
viously locked. The locking function does not merge adjacent regions; if two locked re- 
gions are adjacent, each region must be unlocked separately. 


Regions should be locked only briefly and should be unlocked before closing a file or exit- 
ing the program. 
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locking 


Return Value 


Compatibility 
See Also 


Example 


The locking function should be used only under OS/2 or under DOS versions 3.0 and later; 
it has no effect under earlier versions of DOS. Also, file sharing must be loaded to use the 
locking function. Note that under DOS versions 3.0 and 3.1, the files locked by parent 
processes may become unlocked when child processes exit. 


The locking function returns 0 if successful. A return value of —1 indicates failure, and 
errno is set to one of the following values: 


Value Meaning 

EACCES Locking violation (file already locked or unlocked). 

EBADF Invalid file handle. 

EDEADLOCK Locking violation. This is returned when the LK_LOCK or 
LK_RLCK flag is specified and the file cannot be locked after 
10 attempts. 

EINVAL An invalid argument was given to the function. 
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creat, open 


/* LOCKING.C: This program opens a file with sharing. It locks some 
* bytes before reading them, then unlocks them. Note that the program 
* works correctly only if the following conditions are met: 


* - The file exists 

= - The program is run under OS/2, under DOS 3.8 or later 

* with file sharing installed (SHARE.COM or SHARE.EXE), or 
* if a Microsoft Networks compatible network is running 

mf 


#Hinclude <io.h> 


#Hinclude <sys\types.h> 
dHinclude <sys\stat.h> 
#include <sys\locking.h> 
d#Finclude <share.h> 
dHinclude <fcnt1l.h> 
dHinclude <stdio.h> 
#tinclude <stdlib.h> 
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void main() 


{ 


int fh, numread; 
long pos, result; 
char buffer[4Q]; 


/* Quit if can't open file or DOS version doesn't support sharing. */ 
fh = sopen( "“locking.c", O_RDWR, SH_DENYNO, S_IREAD | S_IWRITE ); 
if( (fh == -1) || (_osmajor < 3) ) 

exit( 1 ); 


/* Lock some bytes and read them. Then unlock. */ 
if( locking( fh, LK_NBLCK, 3@L ) != -1 ) 
{ ? 
printf( "No one can change these bytes while I'm reading them\n" ); 
numread = read( fh, buffer, 30 ); 
printf( "4d bytes read: %.30s\n", numread, buffer :); 
locking( fh, LK_UNLCK, 38L ); 
printf( "Now I'm done. Do what you will with them\n" ); 
} 
else 
perror( "Locking failed\n" ); 


close( fh ); 


Output 


No one can change these bytes while I'm reading them 
30 bytes read: /* LOCKING.C: This program ope 
Now I'm done. Do what you will with them 
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Description Calculate logarithms. 

#include <math.h> 

double log( double x ); 

double log10( double x ); 

long double logl( long double x ); 

long double log101( long double x ); 

x Value whose logarithm is to be found 
Remarks The log and log10 functions calculate the natural logarithm and the base-10 logarithm, re- 


Return Value 


Compatibility 


See Also 


Example 


spectively, of x. The log] and log101 functions are the 80-bit counterparts and use the 80- 
bit, 10-byte coprocessor form of arguments and return values. See the reference page on 
the long double functions for more details on this data type. 


The log functions return the logarithm of the argument x. If x is negative, the functions 
print a DOMAIN error message to stderr, return the value -HUGE_VAL, and set errno to 
EDOM. If x is 0, the functions print a SING error message to stderr, return the value 
—-HUGE_VAL, and set errno to ERANGE. 


Error handling can be modified by using the matherr or _matherr] routine. 
log, log10 

MANS! @ DOS WM OS/2 UNIX 8 XENIX 

logl, log101 
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exp, matherr, pow functions 


/* LOG.C: This program uses log and 10g1@ to calculate the natural 
* logarithm and the base-18 logarithm of 9,000. 


ay 


#Finclude <math.h> 
#Finclude <stdio.h> 
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void main() 

{ 
double x = 9000.9; 
double y; 


y = log( x ); 

printf( "log( %.2f ) = 4f\n", x, y ); 

y = logl@( x ); 

printf( "logl@( %.2f ) = 4f\n", x, y )3 


Output 
log( 9808.00 ) = 9.194980 
1og1@( 9008.98 ) = 3.954243 
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The 8087 family of numeric coprocessor chips supports the 80-bit precision floating-point 
data type. In Microsoft C, version 6.0, the long double functions, whose names end with I, 
map the C long double type into this 80-bit, 10-byte form. Unlike the regular floating- 
point functions (such as acos), which return values of type double, these long double func- 
tions (such as acosl) return values of type long double. The long double functions also 
return their values on the coprocessor stack for all calling conventions. 


The long double type is also supported by the addition of the “L” prefix for a floating- 
point format specification in the printf and scanf family of functions. 


The long double versions are described on the reference pages for their regular counter- 
parts. These are the regular C run-time math functions with corresponding long double 


equivalents: 

Regular Function Long Double Form 
acos | acosl 
asin asinl 
atan atanl 
atan2 atan21 
atof _atold 
cabs cabsl 
ceil ceill 

cos cosl 
cosh coshl 
exp expl 
fabs fabsl 
floor floor! 
fmod fmodl — 
frexp frexpl : 
hypot hypotl 
Idexp Idexpl 
log logl 
log10 log101 
matherr _matherr! 
modf modfl 


long double Functions 


pow 
sin 
sinh 
sqrt 
tan 


tanh 


powl 
sinl 
sinhl 
sqrtl 
tanl 


tanhl 
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463 longjmp 


Description Restores stack environment and execution locale. 
#include <setjmp.h> 


void longjmp( jmp_buf ev, int value ); 


env Variable in which environment is stored 
value Value to be returned to setjmp call 
Remarks The longjmp function restores a stack environment and execution locale previously saved 


in env by setjmp. The setjmp and longjmp functions provide a way to execute a nonlocal 
goto; they are typically used to pass execution control to error handling or recovery code 
in a previously called routine without using the normal call and return conventions. 


A call to setjmp causes the current stack environment to be saved in env. A subsequent 
call to longjmp restores the saved environment and returns control to the point immedi- 
ately following the corresponding setjmp call. Execution resumes as if value had just been 
returned by the setjmp call. The values of all variables (except register variables) that are 
accessible to the routine receiving control contain the values they had when longjmp was 
called. The values of register variables are unpredictable. 


The longjmp function must be called before the function that called setjmp returns. If 
longjmp is called after the function calling setjmp returns, unpredictable program be- 
havior results. 


The value returned by setjmp must be nonzero. If value is passed as 0, the value 1 is substi- 
tuted in the actual return. 


Observe the following three restrictions when using longjmp: 


1. Do not assume that the values of the register variables will remain the same. The values 
of register variables in the routine calling setjmp may not be restored to the proper 
values after longjmp is executed. 


2. Do not use longjmp to transfer control from within one overlay to within another. The 
overlay manager keeps the overlay in memory after a call to longjmp. 


3. Do not use longjmp to transfer control out of an interrupt-handling routine unless the 
interrupt is caused by a floating-point exception. In this case, a program may return 
from an interrupt handler via longjmp if it first reinitializes the floating-point math 
package by calling _fpreset. 


Return Value None. 
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Compatibility MANS! @ DOS 8 OS2 UNIX Mi XENIX 
See Also setjmp 


Example See the example for _fpreset. 


465 _trotl, _lrotr 


Description Rotate bits to the left (_Irotl) or right (_Irotr). 
#include <stdlib.h> 


unsigned long _Irotl( unsigned long value, int shift ); 


unsigned long _lIrotr( unsigned long value, int shift ); 


value Value to be rotated 
shift Number of bits to shift 
Remarks The _Irotl and _Irotr functions rotate value by shift bits. The _lrotl function rotates the 


value left. The _Irotr function rotates the value right. Both functions “wrap” bits rotated 
off one end of value to the other end. 


Return Value Both functions return the rotated value. There is no error return. 
Compatibility O ANS! @& DOS # OS2 CO UNIX O XENIX 


See Also _rotl, _rotr 


Example 


/* LROT.C */ 
#Hinclude <stdlib.h> 
dHinclude <stdio.h> 


void main() 
{ 
unsigned long val = @x@fac35791; 


printf( "@x%8.81x rotated left eight times is @x%8.81x\n", 
val, _lrotl( val, 8 ) ); 

printf( "@x%8.81x rotated right four times is 0x%8.81x\n", 
val, _lrotr( val, 4 ) ); 


Output 


O@xfac35791 rotated left eight times is 9xc3579lfa 
Oxfac35791 rotated right four times is @x1lfac3579 


lsearch 
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Description 


Remarks 


Return Value 


Performs a linear search for a value; adds to end of list if not found. 
#include <search.h> Required only for function declarations 


char *Isearch( const void *key, const void *base, unsigned int *num, 
unsigned int width, int (*compare )( const void *elem/, const void *elem2 ) ); 


key Object to search for 

base Pointer to base of search data 

num Number of elements 

width Width of elements 

compare Pointer to comparison routine 

elem! Pointer to the key for the search 

elem2 Pointer to the array element to be compared with the key 


The Isearch function performs a linear search for the value key in an array of num ele- 
ments, each of width bytes in size. (Unlike bsearch, Isearch does not require the array to 
be sorted.) The base argument is a pointer to the base of the array to be searched. 


If key is not found, Isearch adds it.to the end of the array. 


The compare argument is a pointer to a user-supplied routine that compares two array ele- 
ments and returns a value specifying their relationship. The Isearch function calls the 
compare routine one or more times during the search, passing pointers to two array ele- 
ments on each call. This routine must compare the elements, then return one of the follow- 
ing values: 


Value Meaning 
Nonzero Elements are different 
0 Elements are identical 


If the key is found, Isearch returns a pointer to the element of the array at base that 
matches key. If the key is not found, Isearch returns a pointer to the newly added item at 
the end of the array. 
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Compatibility O ANS! @ DOS HF OS/2 W@ UNIX’ Wf XENIX 
See Also bsearch, Ifind 


Example See the example for Ifind. 


lseek 
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Description 


Remarks 


Return Value 


Moves a file pointer to the specified location. 


#include <io.h> Required only for function declarations 


#include <stdio.h> 


long Iseek( int handle, long offset, int origin ); 


handle Handle referring to open file 
offset Number of bytes from origin 
origin Initial position 


The Iseek function moves the file pointer associated with handle to a new location that is 
offset bytes from origin. The next operation on the file occurs at the new location. The 
origin argument must be one of the following constants, which are defined in STDIO.H: 


Origin Definition 

SEEK_SET Beginning of file 

SEEK_CUR Current position of file pointer 
SEEK_END End of file 


The Iseek function can be used to reposition the pointer anywhere in a file. The pointer can 
also be positioned beyond the end of the file. However, an attempt to position the pointer 
before the beginning of the file causes an error. 


The Iseek function returns the offset, in bytes, of the new position from the beginning of 
the file. The function returns —1L to indicate an error and sets errno to one of the follow- 
ing values: 


Value Meaning 
EBADF Invalid file handle 
EINVAL Invalid value for origin, or position specified by offset is 


before the beginning of the file 


On devices incapable of seeking (such as terminals and printers), the return value is 
undefined. 
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Compatibility O ANS! ™@ DOS # OS/2. HM UNIX Mi XENIX 


See Also fseek, tell 


Example 


/* LSEEK.C: This program first opens a file named LSEEK.C. 
* It then uses lseek to find the beginning of the file, 

* to find the current position in the file, and to find 
* the end of the file. 

*/ 


#Hinclude <io.h> 
#Hinclude <fcentl.h> 
dHinclude <stdlib.h> 
dHinclude <stdio.h> 


void main() 
{ 


int fh; 
long pos; /* Position of file pointer */ 
char buffer[10]; 


fh = open( “Iseek.c", O_RDONLY ); 


/* Seek the beginning of the file: */ 
pos = lseek( fh, OL, SEEK_SET ); 
if( pos == -l1L ) 
perror( "“lseek to beginning failed” ); 
else 
printf( “Position for beginning of file seek = %1d\n", pos ); 


/* Move file pointer a little */ 
read( fh, buffer, 18 ); 


/* Find current position: */ 
pos = lseek( fh, OL, SEEK_CUR ); 
if( pos == -1L ) 
perror( “lseek to current position failed" ); 
else 
printf( "Position for current position seek = %ld\n", pos ); 
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/* Set the end of the file: */ 
pos = lIseek( fh, @L, SEEK_END ); 
if( pos == -1L ) 
perror( "lseek to end failed" ); 
else 
printf( "Position for end of file seek = %1ld\n", pos ); 


close( fh ); 


Output 


Position for beginning of file seek = @ 
Position for current position seek = 19 
Position for end of file seek = 1183 
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Description Converts a long integer to a string. 
#include <stdlib.h> Required only for function declarations 


char “Itoa( long value, char *string, int radix ); 


value Number to be converted 
string String result 
radix Base of value 
Remarks The Itoa function converts the digits of value to a null-terminated character string and 


stores the result (up to 33 bytes) in string. The radix argument specifies the base of value, 
which must be in the range 2—36. If radix equals 10 and value is negative, the first charac- 
ter of the stored string is the minus sign (—). 


Return Value The Itoa function returns a pointer to string. There is no error return. 
Compatibility O ANS! M@ DOS M OS/72 OF UNIX OC XENIX 


See Also itoa, ultoa 


Example 


/* ITOA.C: This program converts integers of various sizes to strings 
* in various radixes. 
Ry} 


#Hinclude <stdlib.h> 
dfinclude <stdio.h> 


void main() 
{ 
char buffer[2Q]; 
int i = 3445; 
long 1 = -344115L; 
unsigned long ul = 123456789QUL; 


_|toa 472 


itoa( i, buffer, 10 ); 

printf( "String of integer 4d (radix 10): %s\n", i, buffer ); 
itoa( i, buffer, 16 ); 

printf( "String of integer 4d (radix 16): @x%s\n", i, buffer ); 
itoa( i, buffer, 2 ); 

printf( "String of integer %d (radix 2): %s\n", i, buffer ); 


ltoa( 1, buffer, 16 ); 
printf( “String of long int 41d (radix 16): Ox%s\n", 1, buffer ); 


ultoa( ul, buffer, 16 ); 
printf( “String of unsigned long %4lu (radix 16): Ox%s\n", ul, buffer ); 


Output 


String of integer 3445 (radix 10): 3445 

String of integer 3445 (radix 16): @Oxd75 

String of integer 3445 (radix 2): 110191110101 

String of long int -344115 (radix 16): Oxfffabfcd 

String of unsigned long 1234567898 (radix 16): 9x4996@2d2 
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_makepath 

Description Creates a single path name. 

#include <stdlib.h> 

void _makepath( char *path, char *drive, char *dir, char *fname, char *ext ); 

path Full path-name buffer 

drive Drive letter 

dir Directory path 

jname File name 

ext File extension 
Remarks The _makepath routine creates a single path name, composed of a drive letter, directory 


path, file name, and file-name extension. The path argument should point to an empty buff- 
er large enough to hold the complete path name. The constant_MAX_PATH, defined in 
STDLIB.H, specifies the maximum size path that the _makepath function can handle. 

The other arguments point to buffers containing the path-name elements: 


Buffer Description 


drive The drive argument contains a letter (A, B, etc.) correspond- 
ing to the desired drive and an optional trailing colon. The 
_makepath routine will insert the colon automatically in the 
composite path name if it is missing. If drive is a null char- 
acter or an empty string, no drive letter and colon will appear 
in the composite path string. 


dir The dir argument contains the path of directories, not includ- 
ing the drive designator or the actual file name. The trailing 
slash is optional, and either forward slashes ( /) or 
backslashes (\) or both may be used in a single dir argument. 
If a trailing slash (/ or\) is not specified, it will be inserted 
automatically. If dir is a null character or an empty string, no 
slash is inserted in the composite path string. 
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fname The fname argument contains the base file name without any 
extensions. If fname is NULL or points to an empty string, no 
file name is inserted in the composite path string. 


ext The ext argument contains the actual file-name extension, 
with or without a leading period (.). The _makepath routine 
will insert the period automatically if it does not appear in ext. 
If ext is a null character or an empty string, no period is in- 
serted in the composite path string. 


There are no size limits on any of the above four fields. However, the composite path must 
be no larger than the MAX_PATH constant. The MAX_PATH limit permits a path name 
much larger than any of the current versions of DOS or OS/2 will handle. 


Return Value None. 
Compatibility OO ANSI mm DOS M@ OS/2 O UNIX O XENIX 


See Also _fullpath, _splitpath 


Example 


/* MAKEPATH.C */ 
dHinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main() 
f 
char path_buffer{_MAX_PATH]; 
char driveL_MAX_DRIVE]; 
char dir{_MAX_DIR]; 
char fnamel_MAX_FNAME]; 
char ext[_MAX_EXT]; 


_makepath( path_buffer, "c", "\\c6@\\clibref\\", “makepath", “c" ); 
printf( "Path created with _makepath: %s\n\n", path_buffer ); 
_splitpath( path_buffer, drive, dir, fname, ext ); 

printf( "Path extracted with _splitpath:\n" ); 

printf( " Drive: &4s\n", drive ); 

printf( " Dir: %@s\n", dir ); 

printf( " Filename: %s\n", fname ); 

printf( " Ext: s\n", ext ); 
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Output 


Path created with _makepath: c:\c6@\clibref\makepath.c 


Path extracted with _splitpath: 
Drive: c: 
Dir: \c6@\clibref\ 
Filename: makepath 
Exts 4c 
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Description 


Remarks 


Allocate memory blocks. 
#include <stdlib.h> For ANSI compatibility (malloc only) 
#include <malloc.h> Required only for function declarations 


void *malloc( size_t size ); 
void _based(void) *_bmalloc( segment seg, size_t size ); 
void far * fmalloc( size_t size ); 


void _near *_nmalloc( size_t size ); 


size Bytes to allocate 


seg Based heap segment selector 


Functions in the malloc family allocate a memory block of at least size bytes. The block 
may be larger than size bytes because of space required for alignment and maintenance in- 
formation. If size is 0, each of these functions allocates a zero-length item in the heap and 
returns a valid pointer to that item. | 


The storage space pointed to by the return value is guaranteed to be suitably aligned for 
storage of any type of object. To get a pointer to a type other than void, use:a type cast on 
the return value. 


In large data models (compact-, large-, and huge-model programs), malloc maps to 
_fmalloc. In small data models (tiny-, small-, and medium-model programs), malloc maps 
to_nmalloc. . 


The _fmalloc function allocates a memory block of at least size bytes in the far heap, 
which is outside the default data segment. The return value is a far pointer to void. 


The _bmalloc function allocates a memory block of at least size bytes in the based heap 
segment specified by the segment selector seg. 


The malloc functions allocate memory in the heap segment specified below. 


~ Function Heap Segment 
malloc Depends on data model of program 
_bmalloc Based heap segment specified by seg value 
_fmalloc Far heap (outside default data segment) 


_nmalloc Near heap (within default data segment) 
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If you are creating programs to run in both real mode and protected mode, you should prob- 
ably bind with APILMR.OBJ as well as API.LIB and OS2.LIB. This is necessary if a pro- 
gram will use the _nmalloc function. 


The functions listed below call the malloc family of routines. In addition, the C start-up 
code uses malloc to allocate storage for the environ/envp and argv strings and arrays. 


The following routines call malloc: 


calloc fseek _searchenv 
execv fsetpos spawnv 
execve fullpath spawnve 
execvp fwrite spawnvp 
execvpe getc spawnvpe 
execl getchar spawnl 
execle getcwd spawnle 
execlp _getcwd spawnlp 
execlpe gets spawnlpe 
fgetc getw strdup 
fgetchar _popen system 
fgets printf scanf 
fprint pute setvbuf 
fputc putchar tempnam 
fputchar putenv ungetc 
fputs puts vfprintf 
fread putw vprintf 
fscanf 


The following routines call malloc only in the multithread run-time libraries (LLIBCMT, 
LLIBCDLL, CDLLOBJS), not in the regular run-time libraries: 


asctime localtime _Strerrpr 
_beginthread mktime tmpfile 
ctime sterror tmpnam 


gmtime 
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Return Value 


Compatibility 


See Also 


The following routines call _nmalloce: 


_nrealloc 

_ncalloc 

_nstrdup 

realloc (in small data models) 


The following routines call _fmalloc: 


_frealloc 

_fcalloc 

_fstrdup 

realloc (in large data models) 


C5.1 Differences In Microsoft C version 5.1, the _fmalloc function would retry allocating within the 


. default data segment (i.e., in the near heap) if sufficient memory was not available outside the default 


data segment. Version 6.0 returns NULL under these conditions. 
In version 5.1, the start-up code used malloc only if wild-card expansion was used. 


The _freect, _memavl, and_memmax functions called malloe in version 5.1 but do not do so in ver- 
sion 6.0. 


The malloc function returns a void pointer to the allocated space. The _nmalloc function 
returns a( void near *) and _fmalloc returns a( void _far * ). The _bmalloc function 
returns a ( void _based( void ) * ). 


The _malloc, fmalloc and _nmalloc functions return NULL if there is insufficient mem- 
ory available. The _bmalloc function returns _NULLOFF if there is insufficient memory 
available. 


Always check the return from the malloc function, even if the amount of memory re- 
quested is small. 


malloc 
MANS! @ DOS WM OS WW UNIX” Wf XENIX 
_bmalloc, fmalloc, _nmalloc 


O ANS! @ DOS WM OS/2 OO UNIX OO XENIX 


calloc functions, free functions, realloc functions 
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EXOT ce i i 


/* MALLOC.C: This program allocates memory with malloc, then frees 
* the memory with free. 
*/ 


d#Hinclude <stdlib.h> /* Definition of _MAX_PATH */ 
dhinclude <stdio.h> 
dHinclude <malloc.h> 


void main() 
{ 
char *string; 


/* Allocate space for a path name */ 
string = malloc( _MAX_PATH ); 
if( string == NULL ) 
printf( “Insufficient memory available\n" ); 
else 
printf( "Memory space allocated for pathname\n" ); 
free( string ); 
printf( “Memory freed\n" ); 


Output 


Memory space allocated for pathname 
Memory freed 
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Description 


Remarks 


Handle math errors. 
#include <math.h> 


int matherr( struct exception *except ); 


int_matherrl( struct _exceptionl *except ); 
except Pointer to structure containing error information 


The matherr functions process errors generated by the functions of the math library. The 
math functions call the appropriate matherr routine whenever an error is detected. The 
_matherrl function uses the 80-bit, 10-byte coprocessor form of arguments and return 
values. See the reference page on the long double functions for more details on this data 


type. 


The user can provide a different definition of the matherr or _matherrl function to carry 
out special error handling. 


When an error occurs in a math routine, matherr is called with a pointer to an exception 
type structure (defined in MATH.H) as an argument. 


The exception structure contains the following elements: 


‘Element Description 

int type Exception type 

char *name Name of function where error occurred 
double arg1, arg2 First and second (if any) argument to function 
double retval Value to be returned by function 


The type specifies the type of math error. It is one of the following values, defined in 
MATH.H: 


Value Meaning 

DOMAIN | Argument domain error 
SING Argument singularity 
OVERFLOW Overflow range error 
PLOSS Partial loss of significance 


TLOSS Total loss of significance 
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Return Value 


Compatibility 


See Also 


Example 


UNDERFLOW Underflow range error 


The structure member name is a pointer to a null-terminated string containing the name of 
the function that caused the error. The structure members arg] and arg2 specify the values 
that caused the error. (If only one argument is given, it is stored in argl.) 


The default return value for the given error is retval. If you change the return value, re- 
member that the return value must specify whether an error actually occurred. If the 
matherr function returns 0, an error message is displayed and errno is set to an appro- 
priate error value. If matherr returns a nonzero value, no error message is displayed, and 
errno remains unchanged. 


The matherr functions should return 0 to indicate an error, and a nonzero value to indicate 
successful corrective action. 


matherr 
O ANS! @ DOS # OS WUNIX’ @ XENIX 
_matherrl 


O ANS! M@ DOS MoOS/7 O UNIX OO XENIX 


acos functions, asin functions, atan functions, bessel functions, cabs, cos functions, exp, 
hypot, log functions, pow, sin functions, sqrt, tan functions 


/* MATHERR.C: To use matherr, you must turn off the Extended Dictionary 
* flag within the Microsoft Programmer's WorkBench environment, or use the 


+ + 


*/ 


/NOE linker option outside the environment. For example: 
CL matherr.c /link /NOE 


. dinclude <math.h> 
#Hinclude <string.h> 
#Hinclude <stdio.h> 
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void main() 
( 
/* Do several math operations that cause errors. The matherr 
* routine handles DOMAIN errors, but lets the system handle 
* other errors normally. 
*/ 
printvt( *log(: 2.0): =-2e\n",. loge =2.8.-) 2s 
printf( "logl1@( -5.@ ) = %e\n", 1loglO( -5.8 ) ); 
printf( "log( @.@ ) = Ze\n", log( 0.0 ) ); 


/* Handie several math errors caused by passing a negative argument 
* to log or 1og1@ (DOMAIN errors). When this happens, matherr returns 
* the natural or base-19 logarithm of the absolute value of the 
* argument and suppresses the uSual error message. 
iad 
int matherr( struct exception *except ) 
{ 
/* Handle DOMAIN errors for log or 1o0g1@. */ 
if( except->type == DOMAIN ) 
{ . 
if( stremp( except->name, "log" ) == @ ) 
{ 
except->retval = log( -(except->argl) ); 
printf( "Special: using absolute value: %s: DOMAIN error\n", 
except->name ); 
return 1; 
} 
else if( stremp( except->name, "logl@" ) == 9 ) 
{ 
except->retval = logl®@( -(except->argl) ); 
printf( "Special: using absolute value: %s: DOMAIN error\n", 
except->name ); 
return 1; 


} 
else 
{ 
printf( "Normal: " ); 
return @; /* Else use the default actions */ 
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Output 


Special: using absolute value: log: DOMAIN error 
log( -2.0 ) = 6.931472e-001 

Special: using absolute value: 10g1@: DOMAIN error 
logl@( -5.0 ) = 6.98970Ge-801 

Normal: log: SING error 

log( 0.8 ) = -1.797693e+308 
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Description Returns the larger of two values. 


#include <stdlib.h> 


type max( type a, type b ); 


type Any numeric data type 


a, b Values of any numeric type to be compared 


Remarks The max macro compares two values and returns the value of the larger one. The argu- 
ments can be of any numeric data type, signed or unsigned. Both arguments and the return 
value must be of the same data type. 


Return Value The macro returns the larger of the two arguments. 
Compatibility O ANS! # DOS mos’ 0 UNIX O XENIX 
See Also min 

Example 


/* MINMAX.C */ 
#include <stdlib.h> 
#Hinclude <stdio.h> 


void main() 
{ 
int a 
int b 


10; 
21; 


printf( "The larger of %d and %4d is @d\n", a, b, max( a, b ) 
printf( "The smaller of 4d and %d is %d\n", a, b, min( a, b ) 


3 
); 
} 


Output 


The larger of 10 and 21 is 21 
The smaller of 10 and 21 is 10 


485 _memavl 
Description Retums the size of memory available. 

#include <malloc.h> Required only for function declarations 

size_t memavl( void ); 
Remarks The _memavl function returns the approximate size, in bytes, of the memory available for 


Return Value 


Compatibility 


See Also 


Example 


dynamic memory allocation in the near heap (default data segment). The _memavl func- 
tion can be used with calloc, malloc, or realloc in tiny, small, and medium memory mod- 
els and with _ncalloc, nmalloc or _nrealloc in any memory model. 


The number returned by the _memavl function may not be the number of contiguous 
bytes. Consequently, a call to malloc requesting allocation of the size returned by 
_memavl may not succeed. Use the _memmax function to find the size of the largest 
available contiguous block of memory. 


The _memavl function returns the size in bytes as an unsigned integer. 
O ANS! #& DOS HOS OO UNIX OO XENIX 


calloc functions, _freect, malloc functions, _memmax, realloc functions 


/* MEMAVL.C: This program uses _memavl to determine the amount of 
* memory available for dynamic allocation. It then uses malloc to 
* allocate space for 5,000 long integers and uses _memav! again to 


a 


* determine the new amount of available memory. 


#Hinclude <malloc.h> \ 
dHinclude <stdio.h> 


void main() 


{ 


long *longptr; 


printf( "Memory available before _nmalloc = %u\n", _memavl() ); 


if( (longptr 


{ 


= _nmalloc( 5008 * sizeof( long ) )) != NULL ) 


printf( "Memory available after _nmalloc = Zu\n", _memavi() ); 
_nfree( longptr ); 


} 
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Output 


Memory available before _nmalloc = 60986 
Memory available after _nmalloc = 48390 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


/* MEMCCPY .C */ 


memecpy, _fmemccpy 


Copy characters from a buffer. 


#include <memory.h> Required only for function declarations 


#include <string.h> Use either STRING.H or MEMORY.H 


void *memccpy( void *dest, void *src, int c, unsigned int count ); 


void far * far _fmemccpy( void far *dest, void _far *sre, int c, unsigned int count ); 


dest Pointer to destination 

STC Pointer to source 

c Last character to copy 
count Number of characters 


The memccpy and _fmemcecpy functions copy 0 or more bytes of src to dest, halting when 
the character c has been copied or when count bytes have been copied, whichever comes 
first. 


The _fmemccpy function is a model-independent (large-model) form of the memccpy 
function. It can be called from any point in any program. 


If the character c is copied, memccpy or _fmemcecpy returns a pointer (or far pointer) to 
the byte in dest that immediately follows the character. If c is not copied, memccpy re- 
turns NULL. 


memecpy 
O ANS! @ DOS 4 OS/2 O UNIX OO XENIX 
_fmemcecpy 


O ANS! @& DOS Mm OS/2 OF UNIX OO XENIX 


memchr, memcmp, memepy, memset 


#Hinclude <memory.h> 
dHinclude <stdio.h> 
dHinclude <string.h> 
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char string1[60] = "The quick brown dog jumps over the lazy fox"; 


void main() 

{ 
char buffer[6l1J; 
char *pdest; 


printf( "Function:\tmemccpy 6@ characters or to character ‘s'\n" ); 
printf( "Source:\t\t%s\n", stringl ); 

pdest = memccpy( buffer, stringl, ‘'s', 68 ); 

*podest = '\@'; 

printf( "Result:\t\t%s\n", buffer ); 

printf( "“Length:\t\t%d characters\n\n", strlen( buffer ) ); 


Output 

Function: memccpy 6@ characters or to character 's' 
Source: The quick brown dog jumps over the lazy fox 
Result: The quick brown dog jumps 


Length: 25 characters 


489 memchr, _fmemehr 
Description Find characters in a buffer. 

#include <memory.h> Required only for function declarations 

#include <string.h> Use either STRING.H (for ANSI compatibility) or 

MEMORY.H 

void *memchr( const void *buf, int c, size_t count ); 

void far * far _fmemchr( const void far *buf, int c, size_t count ); 

buf Pointer to buffer 

c Character to look for 

count Number of characters 
Remarks The memchr and _fmemchr functions look for the first occurrence of c in the first count 


Return Value 


Compatibility 


See Also 


Example 
/* MEMCHR.C */ 


bytes of buf. They stop when they find c or when they have checked the first count bytes. 


The _fmemchr function is a model-independent (large-model) form of the memchr func- 
tion. It can be called from any point in any program. - 


If successful, memchr or _fmemchr returns a pointer (or a far pointer) to the first location 
of c in buf. Otherwise, they return NULL. 


memchr 
@ ANSI | @ DOS 8 OS/ W UNIX WW XENIX 
_fmemchr 


O ANS! @ DOS WMoSs2 0 UNX Oi XENIX 


memccpy, memcmp, memcpy, memset, strchr 


include <mémory.h> 
dHinclude <stdio.h> 
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int ch= 'r'; 
char str[] = 
char string[] = 
char fmt1[] 
char fmt2[] 


void main() 

{ 
char *pdest; 
int result; 


"lazy"; 

"The quick brown dog jumps over the lazy fox"; 

‘ 1 2 3 4 Shier 
"12345678901234567898123456789012345678901234567890" ; 


printf( "String to be searched:\n\t\t%s\n", string ); 
printf( "\t\t%s\n\t\t%s\n\n", fmtl, fmt2 ); 


printf( “Search char:\t%c\n", ch ); 
pdest = memchr( string, ch, sizeof( string ) ); 
result = pdest - string + 1; 


if( pdest != 


NULL ) 


printf( “Result:\t\t%c found at position %d\n\n", ch, result ); 


else 


printf( "Result:\t\t%c not found\n" ); 


Output 


String to be searched: 


Search char: 
Result: 


The quick brown dog jumps over the lazy fox 
if 2 3 4 5 
12345678901234567890123456789812345678901234567890 


r 
r found at position 12 
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Description Compare characters in two buffers. 

#include <memory.h> Required only for function declarations 

#include <string.h> Use either STRING.H (for ANSI compatibility) or 

MEMORY.H 

int memcmp( const void *bufl, const void *buf2, size_t count ); 

int far _fmemecmp( const void _far *bufl, const void _far *buf2, size_t count ); 

bufl First buffer 

buf2 . Second buffer 

count Number of characters 
Remarks The memcmp and _fmemcmp functions compare the first count bytes of buf] and buf2 


Return Value 


Compatibility 


and return a value indicating their relationship, as follows: 


Value Meaning 

<0 bufl less than buf2 
=0 bufl identical to buf2 
>0 bufl greater than buf2 


The _fmemcmp function is a model-independent (large-model) form of the memcmp 
function. It can be called from any point in program. 


There is a semantic difference between the function version of mememp and its intrinsic 
version. The function version supports huge pointers in compact-, large-, and huge-model 
programs, but the intrinsic version does not. 


The memcmp function returns an integer value, as described above. 


memcmp 
MANS! @ DOS 8 OS WUNIX’ MW XENIX 
_fmemcmp 


QO ANS! @ DOS MW OS/2 CJ UNIX OO XENIX 


mememp, _fmemcmp 
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See Also 


Example 


memcecpy, memchr, memcpy, memset, strcmp, strncmp 


/* MEMCMP.C: This program uses memcmp to compare the strings named 
* first and second. If the first 19 bytes of the strings are 
* equal, the program considers the strings to be equal. 


wi 


#Hinclude <string.h> 
dHinclude <stdio.h> 


void main() 

{ 
char first[] 
char second[] 
int result; 


"12345678981234567890" ; 
"12345678981234567891" ; 


printf( "Compare '%.19s' to '%.19s':\n",. first, second ); 


result = memcmp( first, second, 19 ); 
if( result < @ ) 

printf( "First is less than second.\n" ); 
else if( result == @ ) . 

printf( "First is equal to second.\n" ); 
else if( result > @ ) 


printf( "First is greater than second.\n" ); 
printf( “Compare '%.20s' to '%.20s':\n", first, 


result = memcmp( first, second, 20 ); 
if( result < @ ) 

printf( “First is less than second.\n" ); 
else if( result == @ ) 

printf( "First is equal to second.\n" ); 
else if( result > @ ) 


printf( "First is greater than second.\n" ); 


second ); 
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Output 


Compare '1234567898123456789' to '1234567890123456789': 
First is equal to second. 

Compare '12345678981234567898' to '12345678901234567891': 
First is less than second. 
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Description 


Remarks 


Return Value 


Compatibility 


Copy characters between buffers. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H (for ANSI compatibility) or 
MEMORY.H 


void *memcpy( void *dest, const void *src, size_t count ); 


void far * far _fmemcepy( void far *dest, const void _far *src, size_t count ); 


dest New buffer 
SIC Buffer to copy from 
count Number of characters to copy 


The memcpy and _fmemepy functions copy count bytes of src to dest. If the source and 
destination overlap, these functions do not ensure that the original source bytes in the over- 
lapping region are copied before being overwritten. Use memmove to handle overlapping 
regions. 


The _fmemepy function is a model-independent (large-model) pom of the memcpy func- 
tion. It can be called from any point in any program. 


There is a semantic difference between the function version of memepy and its intrinsic 
version. The function version supports huge pointers in compact-, large-, and huge-model 
programs, but the intrinsic version does not. 


The memcpy and _fmemepy functions return a pointer to dest. 


memcpy 
M@ ANSI & DOS BOs/ WUNIX WX XENIX 


_fmemcpy 


[] ANS! M@ DOS WM OS/ O UNIX OO XENIX 
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See Also memccpy, memchr, memcmp, memmove, memset, strcpy, strncpy 


Example __ 


/* MEMCPY.C. Illustrate overlapping copy: memmove handles it 
* correctly; memcpy does not. 
ees 

d#finclude <memory.h> 

#Hinclude <string.h> 

dHinclude <stdio.h> 


char stringl[60] "The quick brown dog jumps over the lazy fox"; 
char string2(6@] = "The quick brown fox jumps over the lazy dog"; 


{s al 2 3 4 5 
‘a 12345678981234567898123456789812345678901234567898 
si 


void main() 
{ 
printf( “Function:\tmemcpy without overlap\n" ); 
printf( "Source:\t\t%s\n", stringl + 40 ); 
printf( “Destination:\t%s\n", stringl + 16 ); 
memcpy( stringl + 16, stringl + 40, 3 ); 
printf( "“Result:\t\t%s\n", stringl ); 
printf( "Length:\t\t%d characters\n\n", strien( stringl ) ); 


/* Restore stringl to original contents */ 
memcpy( stringl + 16, string2 + 40, 3 ); 


printf( "Function:\tmemmove with overlap\n" ); 

printf( "“Source:\t\t%s\n", string2 + 4 ); 

printf( "Destination:\t%s\n", string2 + 18 ); 

memmove( string2 + 10, string2 + 4, 40 ); 

printf( "Result:\t\t%s\n", string2 ); 

printf( "“Length:\t\t%d characters\n\n", strlen( string2 ) ); 


printf( “Function:\tmemcpy with overlap\n" ); 

printf( “Source:\t\t%s\n", stringl + 4 ); 

printf( "Destination: \t%s\n", stringl + 10 ); 

memcpy( stringl + 10, string] + 4, 4@ ); 

printf( "“Result:\t\t%s\n", stringl ); 

printf( “Length:\t\t%d characters\n\n", strlen( stringl ) ); 
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Output 

Function: memcpy without overlap 

Source: fox 

Destination: dog jumps over the lazy fox 

Result: The quick brown fox jumps over the lazy fox 
Length: 43 characters 

Function: memmove with overlap 

Source: quick brown fox jumps over the lazy dog 
Destination: - brown fox jumps over the lazy dog 

Result: The quick quick brown fox jumps over the lazy dog 
Length: 49 characters 

Function: memcpy with overlap 

Source: quick brown dog jumps over the lazy fox 
Destination: brown dog jumps over the lazy fox 

Result: The quick quick quick quick quick quick quick quic 


Length: 5@ characters 
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Description Compare characters in two buffers (case-insensitive). 
#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H or MEMORY.H 


int memicmp( void *buf], void *buf2, unsigned int count ); 


int far _fmemicmp( void far *bufl, void _far *buf2, unsigned int count ); 


bufl First buffer 
buf2 Second buffer 
count Number of characters 
Remarks The memicmp and _fmemicmp functions compare the first count characters of the two 


buffers buf] and buf2 byte-by-byte. The comparison is made without regard to the case of 
letters in the two buffers; that is, uppercase and lowercase letters are considered equiv- 
alent. The memicmp and _fmemicmp functions return a value indicating the relationship 
of the two buffers, as follows: 


Value Meaning 

<0 bufl less than buf2 
=0 bufl identical to buf2 
>0 bufl greater than buf2 


The _fmemicmp function is a model-independent (large-model) form of the memicmp 
function. It can be called from any point in any program. 


Return Value The memicmp and _fmemicmp functions return an integer value, as described above. 


Compatibility memicmp 
O ANS! @ DOS MW OS/2 WM UNIX @ XENIX 
_fmemicmp 


O ANS! M@ DOS WM oOS/?2 OO UNIX O XENIX 
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See Also memccpy, memchr, memcmp, memcpy, memset, stricmp, strnicmp 


Example 


/* MEMICMP.C: This program uses memicmp to compare the first 
* 29 letters of the strings named first and second without 
* regard to the case of the letters. 
ap 


#Hinclude <memory.h> 
#Hinclude <stdio.h>- 
#Hinclude <string.h> 


void main() 
{ 
int result; 
char first{] = "Those Who Will Not Learn from History"; 
char second({] = “THOSE WHO WILL NOT LEARN FROM their mistakes"; 
/* Note that the 29th character is right here * */ 


printf( "Compare '%.29s' to '%.29s'\n", first, second ); 
result = memicmp( first, second, 29 ); 
if( result < @ ) 
printf( "First is less than second.\n" ); 
else if( result == @ ) 
printf( "First is equal to second.\n" ); 
else if( result > @ ) 
printf( "First is greater than second.\n" ); 


Output 


Compare ‘Those Who Will Not Learn from’ to ‘THOSE WHO WILL NOT LEARN FROM’ 
First is equal to second. 
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Description Finds the size of the largest contiguous memory block. 
#include <malloc.h> 
size_t memmax( void ); 


Remarks The _memmax function returns the size (in bytes) of the largest contiguous block of 
memory that can be allocated from the near heap (i.e., the default data segment). Calling 
_nmalloc with the value returned by the _memmax function will succeed as long as 
_memmax retums a nonzero value. 


Return Value The function returns the block size, if successful. Otherwise, it returns 0, indicating that 
| nothing more can be allocated from the near heap. 


Compatibility O ANSI @ DOS gw OS/2 C) UNIX Ol XENIX 
See Also malloc functions, msize functions 
Example 


/* MEMMAX.C: This program uses _memmax and _nmalloc to allocate 
* the largest block of memory available in the near heap. 
*/ 


dHinclude <stddef.h> 
d#Hinclude <malloc.h> 
dHinclude <stdio.h> 


void main() 

{ 
size_t contig; 
char *p; 


_memmax . 500 


/* Determine contiguous memory size */ 

contig = _memmax(); 

printf( "Largest block of available memory is %u bytes long\n", contig ); 
if( contig ) 

{ 


p = _nmalloc( contig * sizeof( int ) ); 
if( p == NULL ) 

printf( “Error with malloc (should never occur)\n" ); 
else 


{ 
printf( “Maximum allocation succeeded\n" ); 
free( p ); 
} 
} 
else 
printf( "Near heap is already full\n" ); 


Output 


Largest block of available memory is 60844 bytes long 
Maximum allocation succeeded 
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memmove, _fmemmove 


Description - 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Move one buffer to another. 
#include <string.h> 


void *memmove( void *dest, const void *src, size_t count ); 


void far* far fmemmove( void _far *dest, const void _far “src, size_t count ); 


dest Destination object 
SIC Source object 


count Number of characters to copy 


The memmove and _fmemmove functions copy count characters from the source (src) to 
the destination (dest). If some regions of the source area and the destination overlap, the 
memmove and _fmemmove functions ensure that the original source bytes in the overlap- 
ping region are copied before being overwritten. 


The _fmemmove function is a model-independent (large-model) form of the memmove 
function. It can be called from any point in any program. 


The memmove and _fmemmove functions return the value of dest. 


memmove 
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_fmemmove 


O ANS! @ DOS WM OS/7 OF UNIX OO XENIX 


memccpy, memepy, strecpy, strnepy 


/* MEMCPY.C. Illustrate overlapping copy: memmove handles it 
* correctly; memcpy does not. - 


ba 2 


#Hinclude <memory.h> 
#include <string.h> 
#include <stdio.h> 
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char string 

char string 

/* 

* 

af 

void main() 

( 
printf ( 
printf ( 
printf ( 
memcpy ( 
printf ( 
printf ( 


/* Resto 
memcpy ( 


printf ( 
printf ( 
printf ( 
memmove ( 
printf ( 
printf ( 


printf ( 
printf ( 
printf ( 
memcpy ( 
printf ( 
printf ( 


Output 


Function: 
Source: 


Destination: 


Result: 
Length: 


Function: 
Source: 


Destination: 


Result: 
Length: 


1[60] 
2[68] 


"The quick brown dog jumps over the lazy fox"; 
"The quick brown fox jumps over the lazy dog"; 

1 2 3 4 5 
12345678991234567898123456789812345678901234567899 


"Function: \tmemcpy without overlap\n" ); 

"Source: \t\t%s\n", stringl + 40 ); 

"Destination: \t%s\n", stringl + 16 ); 

stringl + 16, stringl + 40, 3 ); 

"Result:\t\t%s\n", stringl ); 

"Length: \t\t%d characters\n\n", strien( stringl )); 


re stringl to original contents */ 
stringl + 16, string2 + 40, 3 ); 


"Function:\tmemmove with overlap\n" ); 

"Source: \t\t%s\n", string2 + 4 ); 
"Destination:\t%s\n", string2 + 190 ); 

string2 + 10, string2 + 4, 40 ); 

"Result: \t\t%s\n", string2 ); 

"Length: \t\t%d characters\n\n", strien( string2 ) ); 


"Function:\tmemcpy with overlap\n" ); 

"Source: \t\t%s\n", stringl + 4 ); 

"Destination: \t%s\n", stringl + 10 ); 

Sstringl + 10, string] + 4, 48 ); 

"Result: \t\t%s\n", stringl ); 

"Length:\t\t%d characters\n\n", strlen( stringl ) ); 


memcpy without overlap 

fox 

dog jumps over the lazy fox 

The quick brown fox jumps over the lazy fox 
43 characters 


memmove with overlap 

quick brown fox jumps over the lazy dog 

brown fox jumps over the lazy dog 

The quick quick brown fox jumps over the lazy dog 
49 characters 
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eae a Ne Se Ee] 


Function: memcpy with overlap 

Source: quick brown dog jumps over the lazy fox 
Destination: brown dog jumps over the lazy fox 

Result: The quick quick quick quick quick quick quick quic 


Length: 5@ characters 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Set buffers to a specified character. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H (for ANSI compatibility) or 
MEMORY.H 


void *memset( void *dest, int c, size_t count ); 


void far * far _fmemset( void _far *dest, int c, size_t count ); 


dest Pointer to destination 
c Character to set 
count Number of characters 


The memset and _fmemset functions set the first count bytes of dest to the character c. 


The _fmemset function is a model-independent (large-model) form of the memset func- 
tion. It can be called from any point in any program. 


There is a semantic difference between the function version of memset and its intrinsic 
version. The function version supports huge pointers in compact-, large-, and huge-model 
programs, but the intrinsic version does not. 


The memset and _fmemset functions return a pointer to dest. 


memset 


MANS! @ DOS @ OS/2 UNIX Mf XENIX 
_fmemset 


O ANS| #@ DOS WMos2 O UNIX’ O XENIKX 


memccpy, memchr, memcmp, memcpy, strnset 


/* MEMSET.C: This program uses memset to set the first four bytes 
* of buffer to "*". 


Lai 
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#Hinclude <memory.h> 
#Hinclude <stdio.h> 


void main() 


{ 
char buffer[] = "This is a test of the memset function"; 


printf( "Before: %s\n", buffer ); 

memset( buffer, ‘'*', 4 ); 

printf( “After: %s\n", buffer ); 
} 


Output 


Before: This is a test of the memset function 
After: **** is a test of the memset function 


min 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Returns the smaller of two values. 
#include <stdlib.h> 
type min( type a, type b )3 


type Any numeric data type 


a,b Values of any numeric type to be compared 


The min macro compares two values and returns the value of the smaller one. The argu- 
ments can be of any numeric data type, signed or unsigned. Both arguments and the return 
value must be of the same data type. 


The macro returns the smaller of the two arguments. 
O ANSI DOS B OS/2 O UNIX OO XENIX 


max 


/* MINMAX.C */ 


#Hinclude <stdlib.h> 


d#Hinclude <stdio.h> 


void main() 


{ 
int a 
int b 


printf ( 
printf ( 


Output 


The larger 


1Q; 
dl; 


"The larger of %d and 4d is 2d\n", a, b, max( a, b) ); 
"The smaller of 4d and 4d is d\n", a, b, min( a, b) ); 


of 18 and 21 is 21 


The smaller of 180 and 21 is 10 


507 mkdir 
Description Creates a new directory. 

#include <direct.h> Required only for function declarations 

int mkdir( char *dirname ); 

dirname Path name for new directory 
Remarks The mkdir function creates a new directory with the specified dirname. Only one 


Return Value 


Compatibility 


See Also 


Example 
/* MAKEDIR.C */ 


directory can be created at a time, so only the last component of dirname can name a new 
directory. 


The mkdir function does not do any translation of path-name delimiters. Both DOS and 
OS/2 accept either “\’ or “/” internally as valid delimiters within path names. 


The mkdir function returns the value 0 if the new directory was created. A return value of 
—1 indicates an error, and errno is set to one of the following values: 


Value Meaning 

EACCES Directory not created. The given name is the name of an 
| existing file, directory, or device. 

ENOENT Path name not found. 


O ANS| DOS WM OS/72 OF UNIX OO XENIX 


chdir, rmdir 


dhinclude <direct.h> 
dHinclude <stdlib.h> 
dHinclude <stdio.h> 
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void main() 
{ . 
int result; 


if( mkdir( “\\testtmp" ) == @ ) 

{ ’ 
printf( "Directory '\\testtmp' was successfully created\n"” ); 
system( "dir \\testtmp" ); 
if( rmdir( "\\testtmp" ) == @ ) 

printf( “Directory '\\testtmp' was successfully removed\n" ); 
else 
printf( "Problem removing directory '\\testtmp'\n" ); 

} 

else 
printf( "Problem creating directory ‘\\testtmp'\n" ); 


Output 
Directory '\testtmp' was successfully created 


The volume label in drive C is OS2. 
Directory of C:\TESTTMP 


<DIR> 6-19-89 11:28a 
<DIR> 6-19-89 11:28a 
2 File(s) 12730368 bytes free 
Directory '\testtmp' was successfully removed 


509 mktemp 
Description Creates a unique file name. 

hak <io.h> Required only for function declarations 

char *mktemp( char *template ); 

template File-name pattern 
Remarks The mktemp function creates a unique file name by modifying the given template argu- 


Return Value 


Compatibility 


ment. The template argument has the form: 
baseXXXXXX 


where base is the part of the new file name that you supply, and the X’s are placeholders 
for the part supplied by mktemp; mktemp preserves base and replaces the six trailing X’s 
with an alphanumeric character followed by a five-digit value. The five-digit value is a 
unique number identifying the calling process. The alphanumeric character is 0 (’0’) the 
first time mktemp is called with a given template. 


In subsequent calls from the same process with copies of the same template, mktemp 
checks to see if previously returned names have been used to create files. If no file exists 
for a given name, mktemp returms that name. If files exist for all previously returned 
names, mktemp creates a new name by replacing the alphanumeric character in the name 
with the next available lowercase letter. For example, if the first name returned is 
t@12345 and this name is used to create a file, the next name returned will be 

ta12345, When creating new names, mktemp uses, in order, ’0’ and then the lowercase 
letters ’a’ through ’z’. 


Note that the original template is modified by the first call to mktemp. If you then call the 
mktemp function again with the same template (i.e., the original one), you will get an 
error. 


The mktemp function generates unique file names but does not create or open files. 


The mktemp function returns a pointer to the modified template. The return value is 
NULL if the template argument is badly formed or no more unique names can be created 
from the given template. 
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See Also fopen, getpid, open, tempnam, tmpfile 


Example 


/* MKTEMP.C: The program uses mktemp to create five unique file names. 
* It opens each file name to ensure that the next name is unique. 
ef 


#Finclude <io.h> 
#Hinclude <string.h> 
#Hinclude <stdio.h> 


char *template = "fnXXXXXX"; 
char *result; 
char names{5](9]; 


void main() 
{ 
int i; 
FILE *fp3 


for( i = @; i < 5; i++ ) 
{ 
strcepy( names[i], template ); 


/* Attempt to find a unique file name: */ 
result = mktemp( names[i] ); 
if( result == NULL ) 
printf( "Problem creating the template" ); 
else 
{ 
if( (fp = fopen( result, "w" )) != NULL ) 
printf( "Unique file name is %s\n", result ); 
else 
printf( “Cannot open %s\n", result ); 
fclose( fp ); 


Unique file name is fn@Q0686 
Unique file name is fnaQ@Q686 
Unique file name is fnb@G686 
Unique file name is fnc@0686 
Unique file name is fnd@0686 


511 mktime 
Description Converts the local time to a calendar value. 

#include <time.h> 

time_t mktime( struct tm *timeptr ); 

timeptr Pointer to time structure 
Remarks The mktime function converts the supplied time structure (possibly incomplete) pointed to 


Return Value 


Compatibility 


See Also 


Example 


by timeptr into a fully defined structure with “normalized” values and then converts it to a 
time_t calendar time value. The structure for the tm is described in the reference page for 
asctime. 


The converted time has the same encoding as the values returned by the time function. 
The original values of the tm_wday and tm_yday components of the ¢imeptr structure are 
ignored, and the original values of the other components are not restricted to their normal 
ranges. 


If successful, mktime sets the values of tm_wday and tm_yday appropriately, and sets 
the other components to represent the specified calendar time, but with their values forced 
to the normal ranges; the final value of tm_mday is not set until tm_mon and tm_year are 
determined. 


DOS and OS/2 do not accommodate dates prior to 1980. If timeptr references a date before 
January 1, 1980, mktime returns —1. 


Note that the gmtime and localtime functions use a single statically allocated buffer for 
the conversion. If you supply this buffer to mktime, the previous contents will be 
destroyed. 


The mktime function returns the specified calendar time encoded as a value of type 
time_t. If the calendar time cannot be represented, the function returns the value —1 cast as 
type time_t. 


MANS! M@ DOS # OS2 OO UNIX JC XENIX 


asctime, gmtime, localtime, time 


/* MKTIME.C: The example takes a number of days as input and returns 
* the time, the current date, and the specified number of days. 


“ef 


mktime 512 


dtinclude <time.h> 
#Hinclude <stdio.h> 


void main() 


{ 


) 


struct tm when; 
time_t now, result; 
int days; 


time( &now ); 

when = *localtime( &now ); 

printf( "Current time is %s\n", asctime( &when ) ); 
printf( “How many days to look ahead: " ); 

scanf( "%d", &days ); 


when.tm_mday = when.tm_mday + days; 
if( (result = mktime( &when )) != (time_t)-1 ) 
printf( “In 4d days the time will be %s\n", 
days, asctime( &when ) ); 
else 
perror( “mktime failed” ); 


Output 


Current time is Mon Jun 19 11:45:28 1989 


How many days to look ahead: 23 
In 23 days the time will be Wed Jul 12 11:45:20 1989 
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modf, modfl 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


/* MODF.C */ 


Split a floating-point value into a mantissa and an exponent. 
#include <math.h> 


double modf( double x, double *intptr ); 


long double modfi( long double x, long double *iniptr ); 


x Floating-point value 


intptr Pointer to stored integer portion 


The modf functions break down the floating-point value x into fractional and integer parts, 
each of which has the same sign as x. The signed fractional portion of x is returned. The in- 
teger portion is stored as a floating-point value at intptr. 


The modfl function uses the 80-bit, 10-byte coprocessor form of arguments and return 
values. See the reference page on the long double functions for more details on this data 


type. 


The modf and modfl functions return the signed fractional portion of x. There is no error 
return. 


modf 
M@ ANSI HB DOS H OS/2 m UNIX M XENIX 
modfl 
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frexp, Idexp 


dFinclude <math.h> 
#Hinclude <stdio.h> 
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void main() 
{ 
double x, y, n: 


x 
hd 


-14.87654321; /* Divide x into its fractional */ 
modf( x, &n ); /* and integer parts */ 


printf( "For %f, the fraction is %f and the integer is %.f\n", x, y, n ); 
} 


Output 


For -14.876543, the fraction is -9.876543 and the integer is -14 


515 movedata 
Description Moves characters to another segment. 

#include <memory.h> Required only for function declarations 

#include <string.h> Use either STRING.H (for ANSI compatibility) or 

MEMORY.H 
void movedata( unsigned int srcseg, unsigned int srcoff, unsigned int destseg, 
unsigned int destoff, unsigned int count ); 

srcseg Segment address of source 

srcoff Segment offset of source 

destseg Segment address of destination 

destoff Segment offset of destination 

count Number of bytes 
Remarks The movedata function copies count bytes from the source address specified by 


Return Value 


Compatibility 


srcseg:srcoff to the destination address specified by destseg:destoff. 


The movedata function was intended to move far data in small-data-model programs. The 
newer model-independent _fmemcpy and _fmemmove functions should be used instead 
of the movedata function. In large-data-model programs, the memcpy and memmove 
functions can also be used. 


Segment values for the srcseg and destseg arguments can be obtained by using either the 
segread function or the FP_SEG macro. 


The movedata function does not handle all cases of overlapping moves correctly. These 
occur when part of the destination is the same memory area as part of the source. The 
memmove function correctly handles overlapping moves. 


None. 
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See Also FP_OFF, FP_SEG, memcpy, memmove, segread 


Example 


/* MOVEDATA.C */ 
dFinclude <memory.h> 
dFinclude <stdio.h> 
dHinclude <string.h> 
#Hinclude <dos.h> 
#Hinclude <malloc.h> 


char _far *src = "This is a test."; 


void main() 
{ 
char _far *dest; 


if( (dest = _fmalloc( 89 )) != NULL ) 
{ 
movedata( FP_SEG( sre ), FP_OFF( src ), 
FPZSEGC dest: ), FPLOFF( dest ),-..fstrien( sre J 1) 
printf( "The source data at “Fp is ‘%Fs'\n", src, sre ); 
printf( "The destination data at #Fp is '%Fs'\n", dest, dest ); 
_ffree( dest ); 
} 


Output 


The source data at 2D@A:02B8 is 'This is a test.' 
The destination data at 3D0B:0016 is ‘This is a test.' 
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_moveto Functions 


Description 


Remarks 


Return Value 


Compatibility 


Move current graphics positions. 
#include <graph.h> 


struct xycoord far _moveto( short x, short y ); 


struct _wxycoord far _moveto_w( double wx, double wy ); 


x,y View-coordinate point 


wx, wy Window-coordinate point 


The _moveto functions move the current position to the specified point. The _moveto 
function uses the view-coordinate point (x, y) as the current position. The _moveto_w func- 
tion uses the window-coordinate point (wx, wy) as the current position. No drawing takes 
place. 


The function returns the coordinates of the previous position. The _moveto function re- 
turns the coordinates in an xycoord structure. The xycoord structure, defined in 
GRAPH.H, contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


The _moveto_w function returns the coordinates in an_wxycoord structure, defined in 
GRAPH.H. The _wxycoord structure contains the following elements: 


Element Description 
double wx x window coordinate 
double wy y window coordinate 
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See Also _lineto functions 


Example 


/* MOVETO.C: This program draws line segments of different colors. */ 


#Hinclude <graph.h> 
fFinclude <stdlib.h> 
#Hinclude <conio.h> 


void main() 

{ 
short x, y, xinc, yinc, color = 1; 
struct videoconfig v; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &v ); 

xinc = v.numxpixels / 58; 

yinc = v.numypixels / 58; 


for( x = @, y = v.numypixels - 1; x < v.numxpixels; x += xinc, y -= yinc ) 
{ 
_setcolor( color++ % 16 ); 
_moveto( x, @ ); 
_lineto( @, y ); 
} 
getch(); 


_setvideomode( _DEFAULTMODE ); 
} 
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_msize Functions 


Description 


Remarks 


Return Value 


Compatibility 


Return the size of a memory block allocated in the heap. 
#include <malloc.h> Required only for function declarations 


size_t _msize( void *memblock ); 
size_t _bmsize(_ segment seg, void _based( void ) *memblock ); 
size_t _fmsize( void far *memblock ); 


size_t _nmsize( void _near *memblock ); 


memblock Pointer to memory block 


Seg Based-heap segment selector 


The _msize family of functions returns the size, in bytes, of the memory block allocated 
by acall to the appropriate version of the calloc, malloc, or realloc functions. 


In large data models (compact-, large-, and huge-model programs), _msize maps to 
_fmsize. In small data models (tiny-, small-, and medium-model programs), _msize maps 
to_nmsize. 


The _nmsize function returns the size (in bytes) of the memory block allocated by a call to 
_nmalloc, and the _fmsize function returns the size (in bytes) of the memory block allo- 
cated by acall to _fmalloc or _frealloc. The _bmsize function returns the size of a block 
allocated in segment seg by a callto _bmalloc, _bcalloc, or _brealloc. 


The location of the memory block is indicated below: 


Function Data Segment 

_msize Depends on data model of program 

_bmsize Based heap segment specified by seg value 
_fmsize Far heap segment (outside default data segment) 
_nmsize Default data segment (inside near heap) 


All four functions return the size (in bytes) as an unsigned integer. 
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See Also calloc functions, _expand functions, malloc functions, realloc functions 


Example 


/* REALLOC.C: This program allocates a block of memory for buffer 

* and then uses _msize to display the size of that block. Next, it 
* uses realloc to expand the amount of memory used by buffer 

* and then calls _msize again to display the new amount of 

* memory allocated to buffer. 

*/ 


#include <stdio.h> 
#Hinclude <malloc.h> 
#Hinclude <stdlib.h> 


void main() 

{ 
long *buffer; 
size_t size; 


if( (buffer = (long *)malloc( 1000 * sizeof( long ) )) == NULL ) 
exit( 1); 


size = _msize( buffer ); 
printf( "Size of block after malloc of 1800 longs: Zu\n", size ); 


/* Reallocate and show new size: */ 

if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) == NULL ) 
exit( 1); 

size = _msize( buffer ); 

printf( “Size of block after realloc of 18000 more longs: %u\n", size ); 


free( buffer ); 


Output 


Size of block after malloc of 1000 longs: 4000 
Size of block after realloc of 1908 more longs: 8000 


521 onexit 
Description Registers a routine to be called at exit time. 

#include <stdlib.h> 

onexit_t onexit( onexit_t func ); 

junc Pointer to function to be called at exit 
Remarks The onexit function is passed the address of a function (func) to be called when the pro- 


Return Value 


Compatibility 


See Also 


Example 


f*®-ONEXITLC  *7 


gram terminates normally. Successive calls to onexit create a register of functions that is 
executed in LIFO (last-in—first-out) order. No more than 32 functions can be registered 
with onexit; onexit returns the value NULL if the number of functions exceeds 32. The 
functions passed to onexit cannot take parameters. 


The onexit function is not part of the ANSI definition, but is instead a Microsoft exten- 
sion. The ANSI-standard atexit function does the same thing as onexit, and should be used 
instead of onexit when ANSI portability is desired. 


All routines passed to onexit should have the _loadds attribute if used in multithread 
dynamic-link libraries. 


The onexit function returns a pointer to the function if successful and returns NULL if 
there is no space left to store the function pointer. 
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af 


exit 


dhinclude <stdlib.h> 
dHinclude <stdio.h> 


/* Prototypes */ 
void fnl( void ), fn2( void ), fn3( void ), fn4( void ); 
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void main() 
{ 

onexit( fnl ); 

onexit( fn2 ); 

onexit( fn3 ); 

onexit( fn4 ); 

printf( "This is executed first.\n" ); 
} 


void fnl() 
{ 


) 


printf( "next.\n" ); 


void fn2() 
{ 
printf( "executed " ); 


void fn3() 
{ 

printf( "is " ); 
} 


void fn4() 
{ 

printf( "This " )s3. 
} 


Output 


This is executed first. 
This is executed next. 
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Description 


Remarks 


open 


Opens a file. 


#include <fentl.h> 
#include <sys\types.h> 


#include <sys\stat.h> 


#include <io.h> Required only for function declarations 


int open( char *filename, int oflag {[, int pmode] ); 


filename File name 
oflag Type of operations allowed 
pmode Permission mode 


The open function opens the file specified by filename and prepares the file for subsequent 
reading or writing, as defined by offag. The oflag argument is an integer expression 

formed from one or more of the manifest constants defined in FCNTL.H (listed below). 
When two or more manifest constants are used to form the oflag argument, the constants 
are combined with the bitwise-OR operator (|). See Section 2.5, “File Handling,” for a dis- 
cussion of binary and text modes. 


The FCNTL.H file defines the following manifest constants: 


Constant Meaning | 

O_APPEND Repositions the file pointer to the end of the file before every 
write operation. 

O_BINARY Opens file in binary (untranslated) mode. 

O_CREAT Creates and opens a new file for writing; this has no effect if 


the file specified by filename exists. 


O_EXCL Returns an error value if the file specified by filename exists. 
Only applies when used with O_CREAT. 


O_RDONLY Opens file for reading only; if this flag is given, neither 
O_RDWR nor O_WRONLY can be given. 


O_RDWR Opens file for both reading and writing; if this flag is given, 
neither O_RDONLY nor O_WRONLY can be given. 


O_TEXT Opens file in text (translated) mode. 
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O_TRUNC Opens and truncates an existing file to zero length; the file 
must have write permission. The contents of the file are de- 
stroyed. If this flag is given, you cannot specify O RDONLY. 


O_WRONLY Opens file for writing only; if this flag is given, neither 
O_RDONLY nor O_RDWR can be given. 


WARNING Use the 0_TRUNC flag with care, as it destroys the complete contents of an existing file. 


Either O RDONLY, O_RDWR, or O_WRONLY must be given to specify the access mode. 
There is no default value for the access mode. 


The pmode argument is required only when O_CREAT is specified. If the file exists, 
pmode is ignored. Otherwise, pmode specifies the file’s permission settings, which are set 
when the new file is closed for the first time. The pmode is an integer expression contain- 
ing one or both of the manifest constants S TWRITE and S_IREAD, defined in 
SYS\STAT.H. When both constants are given, they are joined with the bitwise-OR opera- 
tor (|). The meaning of the pmode argument is as follows: 


Value Meaning 
S_IWRITE Writing permitted 
S IREAD Reading permitted 


S IREAD | S_IWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. Under DOS and OS/2, all files are 
readable; it is not possible to give write-only permission. Thus the modes S_IWRITE and 
S_IREAD | S_IWRITE are equivalent. 


The open function applies the current file-permission mask to pmode before setting the per- 
missions (see umask). . 


The filename argument used in the open function is affected by the DOS APPEND com- 
mand. 


Note that under DOS versions 3.0 and later, a problem occurs when SHARE is installed 
and a new file is opened with oflag set to O_ CREAT |O_RDONLY or O_CREAT | 

O _WRONLY and pmode set to S IREAD. Under these conditions, the operating system 
prematurely closes the file during system calls made within open. This problem does not 
occur under OS/2. 


To work around the problem, open the file with the pmode argument set to S TWRITE. 
Then close the file and use chmod to change the access mode back to S_ IREAD. Another 
work-around is to open the file with pmode set to S IREAD and oflag set to.O0_CREAT | 
O_RDWR. 
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Return Value The open function returns a file handle for the opened file. A return value of —1 indicates 
an error, and errno is set to one of the following values: 


Value Meaning 


EACCES Given path name is a directory; or an attempt was made to 
open a read-only file for writing; or a sharing violation oc- 
curred (the file’s sharing mode does not allow the specified 


operations). 
EEXIST The O_CREAT and O_EXCL flags are specified, but the 
named file already exists. 
EINVAL An invalid oflag or pmode argument was given. 
EMFILE No more file handles available (too many open files). 
ENOENT File or path name not found. 
Compatibility O ANSi #& DOS & OS/2 HB UNIX’ WB XENIX 
See Also access, chmod, close, creat, dup, dup2, fopen, sopen, umask 


Example 


/* OPEN.C: This program uses open to open a file named OPEN.C for input 
* and a file named OPEN.OUT for output. The files are then closed. 
as 


#tinclude <fcntl].h> 
#Hinclude <sys\types.h> 
#include <sys\stat.h> 
#Hinclude <io.h> 
dFinclude <stdio.h> 


void main() 
{ 
int fhl, fh2; 
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fhl = open( "OPEN.C", O_RDONLY ); 

if( fhl == -1 ) 
perror( “open failed on input file" ); 

else 

{ m 
printf( "open succeeded on input file\n" ); Pe 
close( fhl ); 

} 


fh2 = open( "OPEN.OUT", O_WRONLY | O_CREAT, S_IREAD | S_IWRITE ); 
if( fh2 == -1 ) 

perror( “open failed on output file" ); 
else 
{ 
printf( “open succeeded on output file\n" ); 
close( fh2 ); 


Output 


open succeeded on input file 
open succeeded on output file 


527 


_ outgtext 


Description 


Remarks 


Return Value 


Prints font-based text in graphics mode. 
#include <graph.h> 

void far _outgtext( unsigned char _far *text ); 
text Text string to output 


The _outgtext function outputs on the screen the null-terminated string that text points to. 
The text is output using the current font at the current graphics position and in the current 
color. 


No formatting is provided, in contrast to the standard console I/O library routines such as 
printf. 


After it outputs the text, outgtext updates the current graphics position. 


The _outgtext function operates only in graphics video modes (e.g.,_MRES4COLOR). 
Because it is a graphics function, the color of text is set by the _setcolor function, not by 
the _settextcolor function. 


None. 


Compatibility O ANS! M#& DOS OF oS? OO UNIX OO XENIX 
See Also _moveto functions, _setcolor, _setfont 

Example 

/* OUTGTXT.C illustrates font output using functions: 

* _registerfonts _setfont _outgtext 

* _unregisterfonts _getfontinfo _getgtextextent 
*  _setgtextvector 

*/ 


#Hinclude <conio.h> 
dtinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <string.h> 
#Hinclude <graph.h> 
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#tdefine NFONTS 6 


unsigned char *face[NFONTS] = 


{ 
}3 


"Courier", "Helvetica", "Times Roman", "Modern", “Script”, “Roman” 


unsigned char *options(NFONTS] = 


{ 


}; 


"courier", “helv", "“tms rmn", “modern", "script", "roman" 


void main() 


{ 


unsigned char list[{2@]; 
char fondir[_MAX_PATH]; 
struct videoconfig vc; 
struct _fontinfo fi; 
short fontnum, x, y; 


/* Read header info from all .FON files in current or given directory. */ 

if( _registerfonts( "*.FON" ) <= @ ) 

{ P 
_outtext( “Enter full path where .FON files are located: " ); 
gets( fondir ); 
strceat( fondir, "\\*.FON" ); 
if( _registerfonts( fondir ) <= @.) 

{ 


_outtext( "Error: can't register fonts" ); 
exit( 1 ); 


} 


/* Set highest available graphics mode and get configuration. */ 
if( !_setvideomode( _MAXRESMODE ) ) 

exit( 1 ); 
_getvideoconfig( &vc ); 


/* Display each font name centered on screen. */ 

for( fontnum = 8; fontnum < NFONTS; fontnum++ ) 

{ 
/* Build options string. */ 
strcat( strcat( strcpy( list, "t'" ), options({fontnum] ), "'"); 
streat( list, "h3@w24b" ); 


_clearscreen( _GCLEARSCREEN ); 
if( _setfont( list ) >= 9 ) 
( 
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/* Use length of text and height of font to center text. */ 
x = (vc.numxpixels / 2) - (_getgtextextent( face{fontnum] ) / 2); 
y = (vc.numypixels / 2) + (_getgtextextent( faceffontnum] ) / 2); 
if( _getfontinfo( &fi ) ) 
{ 
_outtext( "Error: Can't get font information" ); 
break; 
) 
_moveto( x, y )3 
if( ve.numcolors > 2 ) 
_setcolor( fontnum + 2 ); 


/* Rotate and display text. */ 
_setgtextvector( 1, @ ); 
_outgtext( facefLfontnum] ); 
_setgtextvector( @, 1 ); 
_outgtext( face[fontnum] ); 
_setgtextvector( -1, 0 ); 
_outgtext( face({fontnum] ); 
_setgtextvector( 8, -1 ); 
_outgtext( faceLfontnum] ); 
} 
else 
{ 
_outtext( “Error: Can't set font: " ); 
_outtext( list ); 
} 
getch(); 
} 
_unregisterfonts(); 
_setvideomode( _DEFAULTMODE ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Prints text of a specified length in graphics mode. 
#include <graph.h> 
void far_outmem( unsigned char _far *text, short length ); 


text Text string to output 


length Length of string to output 


The _outmem function outputs the string that text points to. The /ength argument specifies 
the number of characters to output. 


Unlike _outtext, the _outmem function prints all characters literally, including ASCII 10, 
13, and 0 as the equivalent graphics characters. No formatting is provided. Text is printed 
using the current text color, starting at the current text position. 


To output text using special fonts, you must use the _outgtext function. 
None. 
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_outtext, _settextcolor, _settextposition, _settextwindow 


/* QUTMEM.C illustrates: 


* _outmem 
*/ 


#Hinclude <stdio. 
#Hinclude <graph. 


void main() 
{ 
int i, len; 


h> 
h> 


char tmp[19]; 
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_clearscreen( _GCLEARSCREEN ); 

for( i = @; i < 256; i++ ) 

{ 
_settextposition( (i % 24) +1, (i / 24) * 7 ); 
len = sprintf( tmp, "%3d %c", i, i ); 
_outmem( tmp, Jen ); 

} 

_settextposition( 24, 1 ); 


outp, outpw 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example - 


/* QUTP.C: This 
* and duration 
*/ 


Outputs a byte (outp) or a word (outpw) at a port. 
#include <conio.h> Required only for function declarations 


int outp( unsigned port, int databyte ); 


unsigned outpw( unsigned port, unsigned dataword ); 


port Port number 
databyte Output value 
dataword Output value 


The outp and outpw functions write a byte and a word, respectively, to the specified out- 
put port. The port argument can be any unsigned integer in the range 0 — 65,535; byte 
can be any integer in the range 0 — 255; and dataword can be any value in the range 

0- 65,535. 


Both outp and outpw are supported in OS/2. You must use a .DEF file to declare the 
IOSEG segment the run-time library uses to perform input/output on the port. In addition, 
the intrinsic (/Oi) versions of these functions do not work unless you put the code in a seg- 
ment that is marked with the IOPL keyword in the .DEF file. 


You cannot do IOPL from a regular code segment, so the run-time library has declared a 
separate code segment called IOSEG. In order to use inp, inpw, outp, or outp in any of 
the protected mode run-time libraries (7LIBCP, LLIBCDLL, LLIBCMT, or CDLLOBJS- 
based DLL), you must have a .DEF file with this line in it: 


SEGMENTS _IOSEG CLASS 'IOSEG_CODE' IOPL 
The functions return the data output. There is no error return. 
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inp, inpw 


program uses inp and outp to make sound of variable tone 
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d#tinclude <conio.h> 
dhinclude <stdio.h> 
d#Hinclude <time.h> 


void Beep( unsigned duration, unsigned frequency ); /* Prototypes */ 
void Sleep( clock_t wait ); 


void main () 
{ 
Beep( 698, 700 ); 
Beep( 523, 500 ); 
} 


/* Sounds the speaker for a time specified in microseconds by duration 
* at a pitch specified in hertz by frequency. 
*/ 
void Beep( unsigned frequency, unsigned duration ) 
{ 
int control; 


/* If frequency is 8, Beep doesn't try to make a sound. */ 
if( frequency ) 
{ 
/* 75 is about the shortest reliable duration of a sound. */ 
if( duration < 75 ) 
duration = 75; 


/* Prepare timer by sending 19111198 to port 43. */ 
outp( @x43, Oxb6 ); 


/* Divide input frequency by timer ticks per second and 
* write (byte by byte) to timer. 

*/ : 

frequency = (unsigned)(1193180L / frequency); 

outp( 0x42, (char)frequency ); 

outp( 0x42, (char)(frequency >> 8) ); 


/* Save speaker control byte. */ 
control = inp( @x61 ); 


/* Turn on the speaker (with bits @ and 1). */ 
outp( 8x61, control | 9x3 ); 
} 


Sleep( (clock_t)duration ); 
/* Turn speaker back on if necessary. */ 


if( frequency ) 
outp( @x61, control ); 


outp, outpw _ 534 


/* Pauses for a specified number of microseconds. */ 
void Sleep( clock_t wait ) 
{ 

clock_t goal; 


goal = wait + clock(); 
while( goal > clock() ) 
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Description Prints text in graphics mode. 
#include <graph.h> 
void far _outtext( unsigned char far “text ); 
text Text string to output 


Remarks The _outtext function outputs the null-terminated string that text points to. No formatting 
is provided, in contrast to the standard console I/O library routines such as printf. This 
function will work in any screen mode. 


Text output begins at the current text position. 


To output text using special fonts, you must use the _outgtext function. 


Return Value None. 
Compatibility O ANS| DOS WM oOS/72 QO UNIX OC XENIX 
See Also _outmem, _settextcolor, settextposition, settextwindow 
Example 
/* QUTTXT.C: This example illustrates text output functions: 
= _gettextcolor _getbkcolor -_gettextposition _outtext 
m _settextcolor _setbkcolor -_settextposition 
xy 


d##Hinclude <conio.h> 
dHinclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [80]; 


void main() 
{ 


/* Save original foreground, background, and text position */ 
short blink, fgd, oldfgd; 

long bgd, oldbgd; 

struct rccoord oldpos; 
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} 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

oldpos = _gettextposition(); 


_clearscreen( _GCLEARSCREEN ); 


/* First time no blink, second time blinking. */ 
for( blink = 0; blink <= 16; blink += 16 ) 
{ 
/* Loop through 8 background colors. */ 
for( bgd = 8; bgd < 8; bgd++ ) 
{ 
_setbkcolor( bgd ); © 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 


/* Loop through 16 foreground colors. */ 
for( fgd = @; fad < 16; fgd++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " %2d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 


537 _pclose 
Description Waits for a child command and closes the stream on the associated pipe. 

#include <stdio.h> Function declaration 

int _pclose( FILE *stream ); 

‘stream File stream fenimied by previous call to _popen 
Remarks The _pclose function waits for a child command and closes the stream on the associated 


Return Value 


Compatibility 


See Also 


Example 


pipe. The argument stream is the return value from a previous call to_popen. The _pclose 
function looks up the process ID of the child command started by the associated _popen 
call, closes the stream, executes a cwait call on the child command, and returns the exit sta- 
tus of the child command. See _pipe for a general discussion of pipes in OS/2. 


The _pclose function returns the exit status of the child command. The format of the return 
value is the same as that for cwait, with the exception that the low-order and high-order 
bytes are swapped. If an error occurs, —1 is returned. 
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A similar function (pclose) is available in the XENIX and UNIX operating environments. 


cwait, pipe, _popen 


See the example for _popen. 


perror 
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Description 


Remarks 


Return Value 
Compatibility 


See Also 


Prints an error message. 


#include <stdio.h> Required only for function declarations 
void perror( const char *string ); 
string String message to print 


The perror function prints an error message to stderr. The string argument is printed first, 
followed by a colon, then by the system error message for the last library call that pro- 
duced the error, and finally by a newline character. If string is a null pointer or a pointer to 
a null string, perror prints only the system error message. 


The actual error number is stored in the variable errno (defined in ERRNO.H). The sys- 
tem error messages are accessed through the variable sys_errlist, which is an array of mes- 
sages ordered by error number. The perror function prints the appropriate error message 
by using the errno value as an index to sys_errlist. The value of the variable sys_nerr is 
defined as the maximum number of elements in the sys_errlist array. 


To produce accurate results, perror should be called immediately after a library routine re- 
turns with an error. Otherwise, the errno value may be overwritten by subsequent calls. 


Under DOS and OS/2, some of the errno values listed in ERRNO.H are not used. These 
additional errno values are reserved for UNIX and XENIX use. See Section 3.3, 
“doserrno, errno, sys_errlist, sys_nerr,” for a list of errno values used on DOS and 
OS/2 and the corresponding error messages. The perror function prints an empty string 
for any errno value not used under the operating system. 


None. 
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clearerr, ferror, strerror 
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/* PERROR.C: This program attempts to open a file named NOSUCHF.ILE. 
* Since this file probably doesn't exist, an error message is displayed. 


ad 


* The same message is created using perror, strerror, and _strerror. 
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dHinclude <fcntl.h> 
#Hinclude <sys\types.h> 
fHinclude <sys\stat.h> 
#Hinclude <io.h> 
#Hinclude <stdlib.h> 
#Hinclude <stdio.h> 
#Hinclude <string.h> 


void main() 
{ 
int fh; 


if( (fh = open( "NOSUCHF.ILE", O_RDONLY )) == -1 ) 
{ 
/* Three ways to create error message: */ 
perror( "“perror says open failed" ); 
printf( "“strerror says open failed: %s\n", strerror( errno ) ); 
printf( _strerror( “_strerror says open failed" ) ); 
} 
else 
{ 
printf( “open succeeded on input file\n" ); 
close( fh ); 


Output 


perror says open failed: No such file or directory 
strerror says open failed: No such file or directory 
_Strerror says open failed: No such file or directory 
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Description 


Remarks 


Analyze a series of data. 
#include <pgchart.h> 


short far pg analyzechart( chartenv far *env, char far * far *categories, 
float _far *values, short 7 ); 


short far pg analyzechartms( chartenv far *env, char far * _far *categories, 
float _far *values, short nseries, short n, short arraydim, 
char _far* far *serieslabels ); 


env Chart environment variable 
categories Array of category variables 
values Array of data values 

nseries Number of series to chart 

n Number of data values to chart 
arraydim Row dimension of data array 
serieslabels Array of labels for series 


The _pg_analyzechart routines analyze a single or multiple series of data without actually 
displaying the presentation-graphic image. 


The _pg_analyzechart function fills the chart environment with default values for a 


‘single-series bar, column, or line chart, depending on the type specified by the call to the 


_pg_defaultchart function. The variables calculated by _pg_analyzechart reflect the data 
given in the arguments categories and values. All arguments are the same as those used 
with the _pg_chart function. 


The _pg_analyzechartms function fills the chart environment with default values for a 
multiseries bar, column, or line chart, depending on which type is specified in the 
_pg_defaultchart function. The variables calculated by _pg_analyzechartms reflect the 
data given in the arguments categories and values. All arguments are the same as those 
used with the _pg_chartms function. 


Boolean flags in the chart environment, such as AUTOSCALE and LEGEND, should be set 
to TRUE before calling either _pg_analyzechart function. This will ensure that the func- 
tion will calculate all defaults. 


For a discussion of the chart environment and related topics, see Section 2.6.2, 
“Presentation-Graphics Functions.” 
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Return Value The _pg_analyzechart and _pg_analyzechartms functions return 0 if there were no er- 
rors. A nonzero value indicates a failure. 


Compatibility O ANS! @ DOS OF oOS/72 OO UNIX OO XENIX 
See Also _pg_chart functions, _pg defaultchart, _pg_initchart 
Example 


/* PGACHART.C: This example illustrates presentation-graphics 
* analyze functions. 

* The example uses 

* _pg_analyzechartms 

* The same principles apply for 

* _pg_analyzepie _pg_analyzechart 

* _pg_analyzescatter _pg_analyzescatterms 


#include <conio.h> 
#include <string.h> 
#tinclude <stdlib.h> 
#Hinclude <graph.h> 
#Hinclude <pgchart.h> 


#tdefine FALSE @ 
#tdefine TRUE 1 


/* Note data declared as a single-dimension array. The multiseries 
* chart functions expect only one dimension. See _pg_chartms 
* example for alternate method using multidimension array. 

*/ 

#tdefine TEAMS 4 

##define MONTHS 3 

float _far values{TEAMS * MONTHS] = { .435, 5223 .671, 

£533: .431, 590, 
.723, 624, .488, 
.329, .226, 401 }; 

{ "May", "June", “July” }; 


char _far *months(MONTHS] = 
= { "Reds", "Sox", "Cubs", "Mets" }; 


char _far *teams{TEAMS] 


void main() 
{ 
chartenv env; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_pg_initchart(); /* Initialize chart system. se 
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/* Default multiseries bar chart */ 

_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 

strcpy( env.maintitle.title, "Little League Records - Default" ); 
_pg_chartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams ); 
getch(); 

_clearscreen( _GCLEARSCREEN ); 


/* Analyze multiseries bar chart with autoscale. This sets all 
* default scale values. We want y axis values to be automatic. 
*/ ; 
_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 
strepy( env.maintitle.title, "Little League Records - Customized" ); 
env.xaxis.autoscale = TRUE; 
_Pg_analyzechartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams ); 


/* Now customize:some of the x axis values. Then draw the chart. */ 
env.xaxis.autoscale = FALSE; 


env.xaxis.scalemax = 1.9; /* Make scale show 8.8 to 1.0. */ 
env.xaxis.ticinterval = @.2; /* Don't make scale too crowded. */ 
env.xaxis.ticdecimals = 3; /* Show three decimals. * / 


strcpy( env.xaxis.scaletitle.title, "Win/Loss Percentage” ); 
_pg_chartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams ); 
getch(); . 


_setvideomode( _DEFAULTMODE ); 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


_pg_analyzepie 


Analyzes a single series of data for a pie chart. 
#include <pgchart.h> 


short far pg analyzepie( chartenv far *env, char far *_far *categories, 
float far *values, short _far *explode, short n ); 


env Chart environment variable 
categories Array of category variables 
values Array of data values 

explode Array of explode flags 

n Number of data values to chart 


The _pg_analyzepie function analyzes a single series of data without actually displaying 
the graphic image. 


The _pg_analyzepie function fills the chart environment for a pie chart using the data con- 
tained in the array values. All arguments are the same as those used in the __pg_chartpie 
function. 


For a discussion of the chart environment and related topics, see Section 2.6.2, 
“Presentation-Graphics Functions.” 


The _pg_analyzepie function returns 0 if there were no errors. A nonzero value indicates a 
failure. . 


O ANS! M@ DOS O OS QO UNIX JO XENIX 
_pg_chartpie, _pg defaultchart, _pg_initchart 


See the example for_pg_analyzechart. 
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Description 


Remarks 


Return Value. 


Analyze a series of data for a scatter chart. 
#include <pgchart.h> 


short far pg analyzescatter( chartenv _far *env, float _far *xvalues, 
float far *yvalues, short n ); 


short far pg analyzescatterms( chartenv _far “env, float far *xvalues, 
float far *yvalues, short nseries, short n, short rowdim, 
char far * far *serieslabels ); 


env Chart environment structure 
xvalues Array of x-axis data values 
yvalues Array of y-axis data values 

n Number of data values to chart 
nseries Number of series to chart 
rowdim Row dimension of data array 
serieslabels Array of labels for series 


The _pg_analyzescatter set of routines analyzes a single or multiple series of data without 
actually displaying the graphic image. 


The _pg_analyzescatter function fills the chart environment for a single-series scatter dia- 
gram. The variables calculated by this function reflect the data given in the arguments 
xvalues and yvalues. All arguments are the same as those used in the _pg_chartscatter 
function. 


The _pg_analyzescatterms function fills the chart environment for a multiseries scatter di- 
agram. The variables calculated by_pg_analyzescatterms reflect the data given in the ar- 
guments xvalues and yvalues. All arguments are the same as those used in the function 
_pg_chartscatterms. 


Boolean flags in the chart environment, such as AUTOSCALE and LEGEND, should be 
set to TRUE before calling pg analyzescatterms, this ensures that the function will cal- 
culate all defaults. 


For a discussion of the chart environment and related topics, see Section 2.6.2, 
“Presentation-Graphics Functions.” 


The _pg_analyzescatter and _pg_analyzescatterms functions return 0 if there were no er- 
rors. A nonzero value indicates a failure. 
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Compatibility O ANS! @ DOS O OS? O UNIX O XENIX 
See Also _pg_chartscatter functions, pg defaultchart, pg initchart 


Example See the example for _pg_analyzechart. 
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Description 


Remarks 


Display single-series or multiseries charts. 
#include <pgchart.h> 


short far pg chart(chartenv far *env, char far * _far *categories, 
float far *values, short n ); 


short far pg chartms(chartenvy far *env, char far * far * categories, 
float _far *values, short nseries, short n, short arraydim, 
char _far* far *serieslabels ); 


env Chart environment variable 
categories Array of category variables 
values Array of data values 

n Number of data values to chart 
nseries Number of series to chart 
arraydim Row dimension of data array 
serieslabels Array of labels for series 


The _pg_chart function displays a single-series bar, column, or line chart, depending on 
the type specified in the chart environment variable (env). 


The _pg_chartms function displays a multiseries bar, column, or line chart, depending on 
the type specified in the chart environment. All the series must contain the same number of 
data points, specified by the argument n. 


The array values is a two-dimensional array containing all value data for every series to 
be plotted on the chart. Each column of values represents a single series. The parameter 
rowdim is the integer value used to dimension rows in the array declaration for values. 


For example, the following code fragment declares the identifier values to be a two- 
dimensional floating-point array with 20 rows and 10 columns: 


j}define ARRAYDIM 2@ 
float values [ARRAYDIM](10]; 
short rowdim = ARRAYDIM; 


Note that the number of columns in the values array cannot exceed 10, the maximum num- 
ber of data series on a single chart. Note also that rowdim must be greater than or equal 
to the argument n, and the column dimension in the array declaration must be greater than 
or equal to the argument series. If n and nseries are set to values less than the full dimen- 
sional size of the values array, only part of the data contained in values will be plotted. 
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The array serieslabels holds the labels used in the chart legend to identify each series. 


For a discussion of the chart environment and related topics, see Section 2.6.2, 
“Presentation-Graphics Functions.” 


Return Value The _pg_ chart and _pg_chartms functions return 0 if there were no errors. A nonzero 
value indicates a failure. 


Compatibility O ANS! m@ DOS Oos2 O UNIX OC XENIX 
See Also _pg_analyzechart functions, _pg defaultchart, _pg_initchart 


Example 


/* PGCHART.C: This example illustrates presentation-graphics support 
* routines and single-series chart routines, including 

* _pg_initchart _pg_defaultchart _pg_chart  -_pg_chartpie 

*/ 


fHinclude <conio.h> 
#Hinclude <graph.h> 
#Hinclude <string.h> 
#Hinclude <stdlib.h> 
#Hinclude <pgchart.h> 


#tdefine COUNTRIES 5 


float _far value({COUNTRIES] = { 42.5, 14.3, Sose4 ZV 34 3256 er 
char _far *category[COUNTRIES] = { "USSR", "France","USA", "UK", "Other" }; 
short _far explode(COUNTRIES] = { @, 15 0, I ) es 


void main() 
{ 
chartenv env; 
short mode = _VRES16COLOR; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_pg_initchart(); /* Initialize chart system. */ 


/* Single-series bar chart */ 

_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 
strcpy( env.maintitle.title, "Widget Production" ); 
_pg_chart( &env, category, value, COUNTRIES ); 
getch(); 

_clearscreen( _GCLEARSCREEN ); 
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/* Single-series column chart */ 

_pg_defaultchart( &env, _PG_COLUMNCHART, _PG_PLAINBARS ); 
strcpy( env.maintitle.title, "Widget Production” ); 
_pg_chart( &env, category, value, COUNTRIES ); 

getch(); 

_Clearscreen( _GCLEARSCREEN ); 


/* Pie chart */ 

_pg_defaultchart( &env, _PG_PIECHART, _PG_PERCENT ); 
strcpy( env.maintitle.title, "Widget Production” ); 
_pg_chartpie( &env, category, value, explode, COUNTRIES ); 
getch(); 


_setvideomode( _DEFAULTMODE ); 


549 _pg_chartpie 
Description Displays a pie chart. 

#include <pgchart.h> 

short far pg chartpie(chartenv far *env, char far * far *categories, 

. float _far *values, short _far *explode, short n ); 

env Chart environment structure 

categories Array of category labels 

values Array of data values 

explode Array of explode flags 

n Number of data values to chart 
Remarks The _pg_chartpie function displays a pie chart for the data contained in the array values. 


Return Value 


Compatibility 


- See Also 


Example 


Pie charts are formed from a single series of data—there is no multiseries version of pie 
charts as there is for other chart types. 


The array explode must be dimensioned so that its length is greater than or equal to the 
argument n. All entries in explode are either 0 or 1. If an entry is 1, the corresponding pie 
slice is displayed slightly removed from the rest of the pie. 


For example, if the explode array is initialized as 
short explode[5] = {@, 1, 0, GB, B); 


the pie slice corresponding to the second entry of the categories array will be displayed 
“exploded” from the other four slices. 


For a discussion of the chart environment and related topics, see Section 2.6.2, 
“Presentation-Graphics Functions.” 


The _pg_chartpie function returns 0 if there were no errors. A nonzero value indicates a 
failure. 


O ANS! @ DOS OF OS/72 UO UNIX OC XENIX 
_pg_analyzepie, pg defaultchart, _pg_initchart 


See the example for _pg_chart. 
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Description 


Remarks 


Return Value 


Display scatter charts. 
#include <pgchart.h> 


short far _pg_chartscatter( chartenv far *env, float _far *xvalues, 
float _far *yvalues, short n ); 


short far _pg_chartscatterms( chartenv _far *env, float _far *xvalues, 
float far *yvalues, short nseries, short n, short rowdim, 
char far * far *serieslabels ); 


env Chart environment structure 
xvalues Array of x-axis data values 
yvalues Array of y-axis data values 

n Number of data values to chart 
nseries | _ Number of series to chart 
rowdim Row dimension of data array 
serieslabels Array of labels for series 


The _pg_chartscatter function displays a scatter diagram for a single series of data. 


The _pg_chartscatterms function displays a scatter diagram for more than one series 
of data. 


The arguments xvalues and yvalues are two-dimensional arrays containing data for the 

x axis and y axis, respectively. Columns for each array hold data for individual series; thus 
the first columns of xvalues and yvalues contain plot data for the first series, the second 
columns contain plot data for the second series, and so forth. 


The n, rowdim, nseries, and serieslabels arguments fulfill the same purposes as those used 
in the _pg_chartms function. See _pg_chartms for an explanation of these arguments. 


For a discussion of the chart environment and related topics, see Section 2.6.2, 
“Presentation-Graphics Functions.” 


The _pg_chartscatter and _pg_chartscatterms functions return 0 if there were no errors. 
A nonzero value indicates a failure. 
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Compatibility O ANS! @ DOS O OS/72 O UNIX O XENIX 


See Also _pg_analyzescatter functions, _pg defaultchart, _pg_initchart 


Example See the example for_pg_ chart. 
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Description 


Remarks 


Initializes the chart environment. 
#include <pgchart.h> 


short far _pg defaultchart( chartenv _far *env, short charttype, short chartstyle ); 


env Chart environment structure 
charttype Chart type 
chartstyle Chart style 


The _pg_defaultchart function initializes all necessary variables in the chart environment 
for the chart type by the variable charttype. 


All title fields in the environment structure are blanked. Titles should be set in the proper 
fields after calling pg defaultchart. 


The charttype variable can be set to one of the following manifest constants: 


Chart Type Description 
_PG_BARCHART Bar chart 
_PG_COLUMNCHART Column chart 
_PG_LINECHART Line chart 
_PG_PIECHART Pie chart 
_PG_SCATTERCHART Scatter chart 


The chartstyle variable specifies the style of the chart with either the number “1” or the 
number “2.” Each of the five types of presentation-graphics charts can appear in two differ- 
ent chart styles, as described below: 


Chart Type Chart Style 1 Chart Style 2 
Bar Side by side Stacked 
Column Side by side Stacked 

Line Points with lines Points only 
Pie Percent No percent 


Scatter Points with lines Points only 
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Return Value 


Compatibility 


See Also 


Example 


In a pie chart, the pieces are “exploded” according to the explode array argument in the 
_pg_chartpie function. In the “percent” format, percentages are printed next to each slice. 
Bar and column charts have only one style when displaying a single series of data. The 
styles “side by side” and “stacked” are applicable only when more than one series appear 
on the same chart. The first style arranges the bars or columns for the different series side 
by side, showing relative heights or lengths. The stacked style emphasizes relative sizes be- 
tween bars and columns. 


The _pg_defaultchart function returns 0 if there were no errors. A nonzero value indi- 
cates a failure. 


O ANS! M@ DOS OF O0S7?2 QO UNIX OO XENIX 


_pg_getchardef, pg getpalette, pg getstyleset, pg hlabelchart, _pg_initchart, 
_pg_resetpalette, pg resetstyleset, pg setchardef, pg setpalette, pg setstyleset, 
_pg_viabelchart 


See the example for_pg_chart. 
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SS aaa La oT Te eS DS TL a GT TT TTS 
Description Gets the pixel bit map for the specified character. 
#include <pgchart.h> 


short far pg getchardef( short charnum, unsigned char _far *chardef ); 


charnum: ASCII number of character 
chardef Pointer to 8-by-8 bit map array 
Remarks The _pg_getchardef function retrieves the current 8-by-8 pixel bit map for the character 


having the ASCII number charnum. The bit map is stored in the chardef array. 


Return Value The _pg_getchardef function returns 0 if there were no errors. A nonzero value indicates 
an error. 
Compatibility O ANS! M@ DOS OF OS/72 O UNIX O XENIX 


See Also _pg_defaultchart, pg initchart, pg setchardef 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_po_getpalette 


Gets palette colors, line styles, and patterns. 
#include <pgchart.h> 


short far pg getpalette( paletteentry far *palette ); 


.. palette Pointer to first palette structure in array 


The _pg_getpalette function retrieves palette colors, line styles, fill patterns, and plot char- 
acters for all palettes. The pointer palette points to an array of palette structures that will 
contain the desired palette values. 


The palette used by the presentation-graphics routines is independent of the palette used by 
the low-level graphics routines. 


The function _pg_getpalette returns 0 if there were no errors, and it returns the value 
_BADSCREENMODE if current palettes have not been initialized by a previous call to 
_pg_setpalette. 


O ANS! @ DOS OF OS/2 O UNIX QO XENIX 


_pg_defaultchart, _pg initchart, pg_resetpalette, pg _setpalette 


/* PGGPAL.C: This example illustrates presentation-graphics palettes 
* and the routines that modify them, including 


* _Pg_getpalette _pg_resetpalette _pg_setstyleset 
* _pg_getstyleset _pg_resetstyleset _pg_vlabelchart 
= _Pg_hlabelchart _pg_setpalette 

*/ 


#Hinclude <conio.h> 
dHinclude <string.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 
#Finclude <pgchart.h> 
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i#tdefine TEAMS 2 
#tdefine MONTHS 3 
float _far valuesCTEAMS][MONTHS] = { { .435, 522, 671) =}, 

{ .533, 431, .401 } ); 
char _far *months[MONTHS] = { "May", "June", "July" } 
char _far *teams({TEAMS] = { "Cubs", "Reds" }; 


fillmap filll = { 0x99, @x33, 0x66, Oxcc, Ox99, Bx33, Ox66, Oxcc }; 
Fillmap fill2 = { Ox99, Oxcc, 0x66, Bx33, Ox99, Bxcc, Ox66, 9x33 }; 
styleset styles; 

palettetype pal; 


void main() 
{ 
chartenv env; 
short mode = _VRES16COLOR; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ’) 
exit( 1); 


_pg_initchart(); /* Initialize chart system. sal 
/* Modify global set of line styles used for borders, grids, and 


sa ae connectors. Note that this change is used before 
_pg_defaultchart, which ml use the style set. 


- 
_pg_getstyleset( styles ); /* Get styles and modify */ 
styles{1] = @x5555; /* style 1 (used for a | 
_pg_setstyleset( styles ); /*  pborders)—-then set new. alld 


_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 


/* Modify palette for data lines, colors, fill patterns, and 
* characters. Note that the line styles are set in the palette, not 
* in the style set, so that only data connectors will be affected. 


bar 
_pg_getpalette( pal ); /* Get default palette. x] 
palClj.plotchar = 16; -/* Set to ASCII 16 and 17. ay 
palC2].plotchar = 17; 
memcpy( pal({1j.fill, filll, 8 ); /* Copy fill masks to palette. */ 
memcpy( pal(2].fill, fill2, 8 ); 

palflj.color = 3; /* Change palette colors. tj 
pal£2].color = 4; 
pal(lj.style = Oxfcfc; /* Change palette line styles. */ 


pal({2].style = 0x0303; 
_pg_setpalette( pal ); /* Put modified palette. */ 
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/* Multiseries bar chart */ 
strcepy( env.maintitle.title, "Little League Records - Customized" ); 
_pg_chartms( &env, months, (float _far *)values, 
TEAMS, MONTHS, MONTHS, teams ); 
getch(); 
_clearscreen( _GCLEARSCREEN ); 


/* Multiseries line chart */ 
_pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE ); 
strcpy( env.maintitle.title, "Little League Records - Customized" ); 
_pg_chartms( &env, months, (float _far *)values, 
TEAMS, MONTHS, MONTHS, teams ); 


/* Print labels. */ 

_pg_hlabelchart( &env, (short)(env.chartwindow.x2 * .75), 
(short) (env.chartwindow.y2 * .10), 
12, "Up and up!" ); 


_pg_vlabelchart( &env, (short)(env.chartwindow.x2 * .75), 
(short) (env.chartwindow.y2 * .45), 
13, “Sliding down!" ); 
getch(); 
_Clearscreen( _GCLEARSCREEN ); 
_pg_resetpalette(); /* Restore default palette ia 
_pg_resetstyleset(); /* and style set. */ 


/* Multiseries bar chart */ 
_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 
strepy( env.maintitle.title, “Little League Records - Default" ); 
_pg_chartms( &env, months, (float _far *)values, 
TEAMS, MONTHS, MONTHS, teams ); 
getch(); 
_Clearscreen( _GCLEARSCREEN ); 


/* Multiseries line chart */ 
_pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE ); 
strepy( env.maintitle.title, "Little League Records - Default" ); 
_Pg_chartms( &env, months, (float _far *)values, 

TEAMS, MONTHS, MONTHS, teams ); 
getch(); 


_setvideomode( _DEFAULTMODE ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Gets the current styleset. 

#include <pgchart.h> 

void far pg getstyleset( unsigned short _far *styleset ); 

Styleset Pointer to current styleset 

The _pg_getstyleset function retrieves the contents of the current styleset. 
None. 

O ANS| @ DOS OF OS2 O UNIX C) XENIX 

_pe, defanltchart, _pg_initchart, pg resetstyleset, _pg_setstyleset 


See the example for_pg_getpalette. — 


559 _pg_hlabelchart 
Description Writes text horizontally on the screen. 

#include <pgchart.h> 

short far pg hlabelchart( chartenv _far *env, short x, short y, short color, 

char far */abel ); 

env Chart environment structure 

x . x-coordinate for text 

y Pixel y-coordinate for text 

color Color code for text 

label Label text 
Remarks The _pg_hlabelchart function writes text horizontally on the screen. The arguments x and 


Return Value 


Compatibility 


See Also 


Example 


y are pixel coordinates for the beginning location of text relative to the upper-left corner of 
the chart window. 


The _pg_hlabelchart functions return 0 if there were no errors. A nonzero value indicates 
a failure. 


O ANS! @ DOS OF OS/ O UNIX OO) XENIX 
_pg_defaultchart, pg initchart, pg vlabelchart 


See the example for_pg_getpalette. 
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Description Initializes presentation graphics. 
#include <pgchart.h> 
short far _pg_initchart( void ); 


Remarks The _pg_initchart function initializes the presentation-graphics package. It initializes the 
color and style pools, resets the chartline styleset, builds default palette modes, and reads 
the presentation-graphics font definition from the disk. This function is required in all pro- 
grams that use presentation graphics. The _pg_initchart function must be called before 
any of the other functions in the presentation-graphics library. 


The _pg_initchart function assumes a valid graphics mode has been established. There- 
fore, it must be called only after a successful call to the library function _setvideomode. 


Return Value The _pg_initchart functions return 0 if there were no errors. A nonzero value indicates a 
failure. | 


Compatibility O ANS} m DOS Oos2 O UNIX O XENI 


See Also _pg_defaultchart, pg getchardef, pg getpalette, pg_getstyleset, 
_pg_hlabelchart, _pg_resetpalette, resetstyleset, pg setchardef, _pg_ setpalette, 
_pg_setstyleset, pg viabelchart, _setvideomode 


Example See the example for _pg_ chart. 


561 _pg_resetpalette 
Description Resets palette colors, line styles, and patterns to default values. 

#include <pgchart.h> 

short far _pg_resetpalette( void ); 
Remarks The _pg_resetpalette function sets the palette colors, line styles, fill patterns, and plot 


Return Value 


Compatibility 
See Also 


Example 


' characters for the palette to the default for the current screen mode. 


The palette used by the presentation-graphics routines is independent of the palette used by 
the low-level graphics routines. 


The _pg_resetpalette function returns 0 if there were no errors. If the screen mode is not 
valid, the value _BADSCREENMODE is returned. 


O ANS! @ DOS OF 0S/2 CQ UNIX OO XENIX 
_pg_defaultchart, pg getpalette, pg initchart, _pg_setpalette 


See the example for_pg_getpalette. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Resets styleset to default values. 
#include <pgchart.h> 
void far _pg_resetstyleset( void ); 


The _pg_resetstyleset function reinitializes the styleset to the default values for the 
current screen mode. 


None. 


O ANS! m DOS Oos2 UNIX OC XENIX 


| _pg_defaultchart, pg getstyleset, pg initchart, pg_setstyleset 


See the example for_pg_getpalette. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


 _ pg_setchardef 


Sets the pixel bit map for the specified character. 
#include <pgchart.h> 
short far _pg_setchardef( short charnum, unsigned char _far *chardef ); 


charnum ASCII number of character 


chardef Pointer to an 8-by-8 bit map array for the character 


The _pg_setchardef function sets the 8-by-8 pixel bit map for the character with the 
ASCII number charnum. The bit map is stored in the chardef array. 


The _pg_setchardef function returns 0 if there was no error. A nonzero value indicates an 
error. 


O ANS| M@ DOS OF O0S2 O UNIX OC XENIX 


_pg_defaultchart, _pg getchardef, pg initchart 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


- Example 


Sets palette colors, line styles, and patterns. 

#include <pgchart.h> 

short far pg setpalette( paletteentry far *palette ); 

palette Pointer to first palette structure in array 


The _pg_setpalette function sets palette colors, line styles, fill patterns, and plot charac- 
ters for all palettes. The pointer palette points to an array of palette structures that contain 
the desired palette values. 


The palette used by the presentation-graphics routines is independent of the palette used by 
the low-level graphics routines. 


The _pg_setpalette function returns 0 if there were no errors. If the new palettes are not 
valid, the value BADSCREENMODE is returned. 


O ANS! DOS OF O0S7?2 QO UNIX O XENIX 


_pg_defaultchart, pg _getpalette, pg initchart, _pg_resetpalette 


See the example for_pg_getpalette. 
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Description Sets the current styleset. 
#include <pgchart.h> 


void far _pg_setstyleset( unsigned short _far *styleset ); 


styleset Pointer to new styleset 
Remarks The _pg_setstyleset function sets the current styleset. 
Return Value None. 


Compatibility O ANS! M@& DOS QO os O UNIX OO XENIX 
See Also _pg_defaultchart, pg _getstyleset, pg initchart, _pg_resetstyleset 


Example See the example for_pg_getpalette. 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


Writes text vertically on the screen. 
#include <pgchart.h> 


short far pg vlabelchart( chartenv far *env, short x, short y, short color, 
char _far */abel ); 


env Chart environment structure 
x Pixel x coordinate for text 

y Pixel y coordinate for text 
color Color code for text 

label Label text 


The _pg_viabelchart function writes text vertically on the screen. The arguments x and y 
are pixel coordinates for the beginning location of text relative to the upper-left corner of 
the chart window. 


The _pg_vlabelchart function returns 0 if there were no errors. A nonzero value indicates 
a failure. : 


O ANSI ™ DOS QO oS/7 QO UNIX O XENIX 
_pg_defaultchart, pg hlabelchart, _pg_initchart 


See the example for _pg_getpalette. 


567 _pie Functions 
Description Draw wedge-shaped figures. 
#include <graph.h> 
short far _pie( short control, short x/, short y/, short x2, short y2, short x3, short y3, 
short x4, short y4 ); 
short far _pie_w( short control, double x/, double y/, double x2, double y2, 
double x3, double y3, double x4, double y4 ); 
short far _pie_wxy( short control, struct _wxycoord far *pwxyl, 
struct _wxycoord far *pwxy2, struct _wxycoord _far *pwxy3, 
struct _wxycoord _far*pwxy4 ); 
control Fill-control constant 
x1, yl Upper-left corner of bounding rectangle 
x2, y2 | Lower-right comer of bounding rectangle 
x3, y3 Start vector 
x4, y4 End vector . 
pwxyl Upper-left corner of bounding rectangle 
pwxy2 Lower-right comer of bounding rectangle 
pwxy3 Start vector 
pwxy4 End vector 
Remarks The _pie functions draw a pie-shaped wedge by drawing an elliptical arc whose center and 


two endpoints are joined by lines. 


The _pie function uses the view coordinate system. The center of the arc is. the center of 
the bounding rectangle specified by the view coordinate points (x/, yl) and (x2, y2). The 
arc starts where it intersects the vector defined by (x3, y3) and ends where it intersects the 
vector (x4, y4). 


The _pie_wxy and _pie_w functions use the window coordinate system. The center of the 
arc is the center of the bounding rectangle specified by the window coordinate pairs pwxyl 
and pwxy2 for _pie_wxy, and by the points (x/, y/) and (x2, y2) for_pie_w. The arc starts 
where it intersects the vector defined by pwxy3 or (x3, y3) and ends where it intersects the 

vector defined by pwxy4 or (x4, y4). 
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Return Value 


Compatibility 


See Also 


Example 


The _wxycoord structure is defined in GRAPH.H and contains the following elements: 


Element Description 
double wx Window x coordinate 
double wy Window y coordinate 


The wedge is drawn using the current color moving in a counterclockwise direction. The 
control parameter can be one of the following manifest constants: 


Constant ~ Action 
_GFILLINTERIOR Fills the figure using the current color and fill mask 
_GBORDER ; Does not fill the figure 


The control option given by GFILLINTERIOR is equivalent to a subsequent call to the 
_floodfill function using the approximate center of the arc as the starting point and the cur- 
rent color (set by _setcolor) as the boundary color. 


These functions return a nonzero value if successful; otherwise, they return 0. 
O ANS! HW DOS OF 0S/72 0 UNIX O XENIX 


_arc functions, _ ellipse functions, _floodfill, _getcolor, _lineto functions, 
_rectangle functions, _setcolor, _setfillmask 


/* PIE.C: This program draws a pie-shaped figure. */ 


#include <stdlib.h> 
dHinclude <conio.h> 
#Hinclude <graph.h> 
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void main() 
{ 
/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_pie( _GBORDER, 88, 58, 240, 158, 240, 12, 9, 150 ); 
getch(); 


_setvideomode( _DEFAULTMODE ); 
) 


_pipe 
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Description 


Remarks 


Creates a pipe for reading and writing. 


#include <fentl.h> For O_BINARY and O_TEXT definitions 
#include <errno.h> errno definitions 
#include <io.h> Prototype declaration 


int _pipe( int *phandles, unsigned int psize, int textmode ); 


phandles[2] Array to hold read and write handles 
psize | Amount of memory to reserve 
textmode File mode 


A pipe is an artificial file-like I/O channel that a program can create and use to pass infor- 
mation to other programs. A pipe is similar to a file in that it has a file pointer or a file de- 
scriptor, or both, and can be read from or written to using the input and output functions of 
the standard library. Unlike a file, a pipe does not represent a specific file or device. In- 
stead, a pipe represents temporary storage in memory that is independent of the program’s 
own memory and is controlled entirely by the operating system. 


Pipes may be used to pass information between programs. For example, the command pro- 
cessor in OS/2 creates a pipe when executing a command such as 


PROGRAM] | PROGRAM2 


The standard output handle of PROGRAM is attached to the pipe’s write handle. The 
standard input handle of PROGRAM 2 is attached to the pipe’s read handle. This elimi- 
nates the need for creating temporary files to pass information to other programs. 


The _pipe function creates a pipe. This function is similar to open but opens the pipe for 
both reading and writing, returning two file handles instead of one. The program can either 
use both sides of the pipe or close the one it does not need. This function typically opens a 
pipe in preparation for linking it to a child process. 


The _pipe function opens a pipe and returns two handles to the pipe in the phandles argu- 
ment. The element phandles[0] contains the read handle, and the element phandles[1] con- 
tains the write handle. Pipe file handles are used in the same way as other file handles. 
(The low-level input and output functions read and write can read from and write to a 


pipe.) 


The psize argument specifies the amount of memory, in bytes, to reserve for the pipe. 
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The textmode argument specifies the translation mode for the pipe. The manifest constant 

O_TEXT specifies a text translation, and the constant O_BINARY specifies binary transla- 

tion. (See fopen for a description of text and binary modes.) If the textmode argument is 0, 

the _pipe function uses the default translation mode specified by the default-mode variable 
fmode. 


In multithread programs, no locking is performed. The handles returned are newly opened 
and should not be referenced by any thread until after the _pipe call is complete. 


Under OS/2, a pipe is destroyed when all its handles have been closed. (If all read handles 
on the pipe have been closed, writing to the pipe will cause an error.) All read and write 
operations on the pipe wait until there is enough data or enough buffer space to complete 
the I/O request. 


Return Value The _pipe function returns 0 if successful. A return value of —1 indicates an error, and 
errno is set to one of the following values: 


Value Meaning 
EMFILE No more file handles available (too many open files) 
ENFILE System file table overflow 


Compatibility O ANS! O DOS #@ OS/2 Hi UNIX Mf XENIX 


A similar function (pipe) is available in the XENIX and UNIX operating environments. 


See Also — cwait, _pclose, _popen 


Example 


/* PIPE.C: This program uses _pipe to pass streams of text to 
* child processes. 
tar | 


#Hinclude <stdlib.h> 

#Finclude <stdio.h> 

#Finclude <io.h> 

#Hinclude <fcnt1l.h> 

#Finclude <process.h> /* pipe */ 
dHinclude <math.h> 
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enum PIPES { READ, WRITE }; /* Constants @ and 1 for READ and WRITE */ 
#tdefine NUMPROBLEM 8 


void main( int argc, char *argvL[] ) 


{ 


int 
char 
int 


hpipe[2]; 
hstr(20]; 
termstat, pid, problem, c; 


/* If no arguments, this is the parent. */ 
if( arge == 1 ) 


{ 


/* Open a sets of pipes. */ 
if( _pipe( hpipe, 256, O_BINARY ) == -1 ) 
exit( 1 ); 


/* Convert pipe read handle to string and pass as argument to 
* spawned child. Program spawns itself (argv[@]). 


*/ 
itoa( hpipe[READJ, hstr, 10 ); 
if( spawnl( P_NOWAIT, argv([@], argv(@], hstr, NULL ) == -1 ) 


printf( "Spawn failed” ); 


/* Put problem in write pipe. Since child is running simultaneously, 
* first solutions may be done before last problem is given. 
af 
for( problem = 1928; problem <= NUMPROBLEM * 1088; problem += 1920 ) 
{ 
printf( "Son, what is the square root of %d?\n", problem ); 
write( hpipeCWRITE], (char *)&problem, sizeof( int ) ); 
} 


/* Wait until child is done processing. */ 
wait( &termstat ); 
if( termstat & Oxff ) 

printf( "Child failed\n" ); 


close( hpipe[READ] ); 
close( hpipe[WRITE] ); 
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/* If there is an argument, this must be the child. */ 
else 


{ 


/* Convert passed string handle to integer handle. */ 
hpipeCREAD] = atoi( argv[1] ); 


/* Read problem from pipe and calculate solution. */ 
for( c = @; c < NUMPROBLEM; c++ ) 
{ 
read( hpipe[READ], (char *)&problem, sizeof( int ) ); 
printf( “Dad, the square root of %d is %3.2f.\n", 
problem, sqrt( (double)problem ) );; 


Output 

Son, what is the square root of 1000? 
Dad, the square root of 1990 is 31.62. 
Son, what is the square root of 2000? 
Son, what is the square root of 3080? 
Dad, the square root of 2000 is 44.72. 
Son, what is the square root of 4800? 
Dad, the square root of 3800 is 54.77. 
Son, what is the square root of 5880? 
Dad, the square root of 4809 is 63.25. 
Son, what is the square root of 6890? 
Dad, the square root of 5000 is 70.71. 
Son, what is the square root of 7800? 
Dad, the square root of 6000 is 77.46. 
Son, what is the square root of 8000? 
Dad, the square root of 7009 is 83.67. 
Dad, the square root of 8000 is 89.44. 
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Description 


Remarks 


Return Value 


Compatibility 


Draw polygon shapes. 
#include <graph.h> 


short far _polygon( short control, struct xycoord _far *points, short numpoints ); 
short far _polygon_w( short control, double _far *points, short numpoints ); 


short far _polygon_wxy( short control, struct wxycoord far *points, 
short numpoints ); 


control . Fill flag - 
points Pointer to an array of structures defining the polygon 
numpoints _ Number of points 


The _polygon functions draw polygons. The border of the polygon is drawn in the current 
color and line style. The _polygon routine uses the view coordinate system (expressed in 
xycoord structures), and the _polygon_wxy and _polygon_w routines use real-valued win- 
dow coordinates (expressed in _wxycoord structures and in pairs of double-precision float- 
ing-point values, respectively). 


The argument points is an array of xycoord or __wxycoord structures or pairs of doubles, 
each of which specifies one of the polygon’s vertices. (For _polygon_w, points[O] and 
points[1] specify the x and y coordinates, respectively, of the first point.) The argument 
numpoints indicates the number of elements (the number of vertices) in the points array. 


The control argument can be one of the following manifest constants: 


Constant Action 
_GFILLINTERIOR Fills the polygon using the current fill mask 
_GBORDER Does not fill the polygon 


The _setwritemode, setlinestyle, and _setfillmask functions all affect the output from 
the_polygon functions. 


The _polygon functions return a nonzero value if the arc is successfully drawn; otherwise, 
they return 0. 
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See Also _ellipse functions, _floodfill, _lineto functions, _pie functions, _rectangle functions, 
_Setcolor, _setfillmask, _setlinestyle, _setwritemode 


Example 


/* POLYGON.C: This program draws a star-shaped polygon. */ 


#Hinclude <conio.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 
dFinclude <math.h> 

#Hinclude <stdlib.h> 


#tdefine PI 3.1415 


void main() 
{ 
short side, radius = 98, x =@, y=@; 
double radians; 
struct xycoord polyside[5]; 
struct videoconfig vc; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_getvideoconfig( &vc ); 
_setvieworg( vc.numxpixels / 2, vc. numypixels / 2 ); 


/* Calculate points of star every 144 degrees, then connect them. */ 
for( side = @; side < 5; sidet+ ) 
{ 
radians = 144 * PI / 180; 
polyside[Lside].xcoord = x + (short)(cos( side * radians ) * radius); 
polysideLside].ycoord = y + (short)(sin( side * radians ) * radius); 
} 
_polygon( _GFILLINTERIOR, polyside, 5 ); 


getch(); 
_setvideomode( _DEFAULTMODE ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Creates a pipe and executes a command. 
#include <stdio.h> Required for function declarations only 
FILE *_popen( char *command, char *mode ); 


command Command to be executed 


mode Mode of returned stream 


The _popen function creates a pipe and asynchronously executes a child copy of the com- 
mand processor with the specified command string command. See _pipe for a general dis- 
cussion of pipes in OS/2. The character string mode specifies the type of access requested, 
as follows: 


Type Description 
ie The calling process can read the child command’s standard 
output via the returned stream. 


"yw" The calling process can write to the child command’s standard 
input via the returned stream. 

"p" Open in binary mode. 

me" Open in text mode. 


See Section 2.7, “Input and Output,” for a discussion of text and binary modes. 


The _popen function returns a stream associated with one end of the created pipe. The 
other end of the pipe is associated with the child command’s standard input or standard out- 
put. If an error occurs, NULL is returned. 


O ANSI! O DOS # OS WW UNIX’ Wf XENIX 


A similar function (popen) is available in the XENIX and UNIX operating environments. 


_pclose, _pipe 


/* POPEN.C: This program uses _popen and _pclose to receive a stream 


mi 


* of text from a child system process. 
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dHinclude <stdio.h> 
dHinclude <stdlib.h> 


void main() 

{ 
char buffer[{128]; 
FILE *chkdsk; 


/* Run CHKDSK so that it writes its output to a pipe. Open pipe 

* with read text attribute so that we can read it like a text file. 

* / 

if( (chkdsk = _popen( “dir po*.c | sort | more", "rt" )) == NULL ) 
exit( 1 ); 


/* Read pipe until end of file. End of file indicates that CHKDSK 
* closed its standard out (probably meaning it terminated). 

*/ 
while( !feof( chkdsk ) ) 

{ 

if( fgets( buffer, 128, chkdsk ) != NULL ) 
printf( buffer ); 
} 


/* Close pipe and print return value of CHKDSK. */ 
printf( "\nChild returned %d\n", _pclose( chkdsk ) ); 


Output 


3 File(s) 12683264 bytes free 
Directory of C:\LIBREF 
The volume label in drive C is 0S2. 


POLYGON C 921 6-14-89 6:51p 
POPEN C 845 6-19-89 2:48p 
POW C 199 6-13-89 6:87p 


Child returned @ 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Calculate x raised to the power of y. 
#include <math.h> 


double pow( double x, double y ); 
long double powl( long double x, long double y ); 


x Number to be raised 


y Power of x 


' The pow and pow! functions compute x raised to the power of y. 


The powl function is the 80-bit counterpart, and it uses an 80-bit, 10-byte coprocessor 
form of arguments and return values. See the reference page on the long double functions 
for more details on this data type. 


The pow and pow! functions return the value of x’. If x is not 0.0 and y is 0.0, pow and 
powl return the value 1. If x is 0.0 and y is negative, pow and powl set errno to EDOM 
and return 0.0. If both x and y are 0.0, or if x is negative and y is not an integer, the func- 
tion prints a DOMAIN error message to stderr, sets errno to EDOM, and returns 0.0. If an 
overflow results, the function sets errno to ERANGE and returns -HUGE_VAL. No mes- 
sage is printed on overflow or underflow. 


The pow function does not recognize integral floating-point values greater than oe such 
as 1.9E100. 


pow 
GANS! DOS dm oOS/ mm UNIX i XENIX 
powl 
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exp, log functions, sqrt 


Example i ee 


/* POW.C */ 


#Hinclude <math.h> 
dHinclude <stdio.h> 
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void main() 
{ 
double x = 2.0, y = 3.0, 2; 


z = pow( x, y ); 


printf( "%.1f to the power of %.1f is %.1f\n", x, y, z ); 
) 


Output 


2.8 to the power of 3.0 is 8.0 
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Description 


Remarks 


Prints formatted output to the standard output stream. 


s 


#include <stdio.h> 
int printf( const char *formart [[, argument]... ); 


format Format control 


argument Optional arguments 


The printf function formats and prints a series of characters and values to the standard out- 
put stream, stdout. The format argument consists of ordinary characters, escape sequen- 
ces, and (if arguments follow format) format specifications. The ordinary characters and 
escape sequences are copied to stdout in order of their appearance. For example, the line 


printf("Line one\n\t\tLine two\n"); 
produces the output 


Line one 
Line two 


If arguments follow the format string, the format string must contain speetiications that de- 
termine the output format for the arguments. 


Format specifications always begin with a percent sign (%) and are read left to right. 
When the first format specification (if any) is encountered, the value of the first argument 
after format is converted and output accordingly. The second format specification causes 
the second argument to be converted and output, and so on. If there are more arguments 
than there are format specifications, the extra arguments are ignored. The results are unde- 
fined if there are not enough arguments for all the format specifications. 


A format specification, which consists of optional and required fields, has the following 
form: 


%o\[flags]| [width] [[.precision] [{F |N |h]1]L}]type 
Format Specification Fields 


Each field of the format specification is a single character or a number signifying a particu- 
lar format option. The simplest format specification contains only the percent sign and a 
type character (for example, %S). The optional fields, which appear before the type charac- 
ter, control other aspects of the formatting. The fields in a printf format specification are 
described in the following list: 
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Field 


type 


flags 


width 


precision 


F,N 


h, 1, L 


Description 


Required character that determines whether the associated ar- 
gument is interpreted as a character, a string, or a number. 
(See Table R.2.) 


Optional character or characters that control justification of 
output and printing of signs, blanks, decimal points, and octal 
and hexadecimal prefixes. (See Table R.3.) More than one 
flag can appear in a format specification. 


Optional number that specifies minimum number of charac- 
ters output. 


Optional number that specifies maximum number of charac- 
ters printed for all or part of the output field, or minimum 
number of digits printed for integer values. (See Table R.4.) 


Optional prefixes that refer to the “distance” to the object 
being printed (near or far). 


F and N are not part of the ANSI definition for printf. They 
are Microsoft extensions that should not be used if ANSI 
portability is desired. 


Optional prefixes that determine the size of the argument ex- 
pected, as shown below: 


Prefix Use 


h Used with the integer types d, i, 0, x, and X 
to specify that the argument is short int, or 
with u to specify short unsigned int. If 
used with %p, it indicates a 16-bit pointer. 


l Used with d, i, 0, x, and X types to specify 
that the argument is long int, or with u to 
specify long unsigned int; also used with 
e, E, f, g, and G types to specify double 
rather than float. If used with %p, it indi- 
cates a 32-bit pointer. 


L Used with e, E, f, g, and G types to specify 
long double. 


If a percent sign is followed by a character that has no meaning as a format field, the char- 
acter is copied to stdout. For example, to print a percent-sign character, use %%. 
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The type character is the only required format field for the printf function; it appears after 
any optional format fields. The type character determines whether the associated argument 
is interpreted as a character, a string, or a number. (See Table R.2.) 


Table R.2. Type Characters for printf 


Character 


d 
i 


mM x O fF 


Type 
int 

int 

int 

int 

int 

int 
double 


double 


double 


double 


double 


int 
String 


Pointer to 
integer 


Far pointer 
to void 


Output Format 


Signed decimal integer. 

Signed decimal integer. 

Unsigned decimal integer. 

Unsigned octal integer. 

Unsigned hexadecimal integer, using “abcdef.” 
Unsigned hexadecimal integer, using “ABCDEF.” 


Signed value having the form [~]dddd.dddd, where dddd is one or 

more decimal digits. The number of digits before the decimal point 
depends on the magnitude of the number, and the number of digits 
after the decimal point depends on the requested precision. 


Signed value having the form [—]d.dddd e [sign]ddd, where d is a 
single decimal digit, dddd is one or more decimal digits, ddd is ex- 
actly three decimal digits, and sign is + or~. 


Identical to the e format, except that E, rather than e, introduces the 
exponent. 


Signed value printed in f or e format, whichever is more compact for 
the given value and precision. The e format is used only when the 
exponent of the value is less than —4 or greater than or equal to the 
precision argument. Trailing zeros are truncated, and the decimal 
point appears only if one or more digits follow it. 


Identical to the g format, except that G, rather than g, introduces the 
exponent (where appropriate). 


Single character. 


Characters printed up to the first null character (’\0’) or until the 
precision value is reached. 


Number of characters successfully written so far to the stream or 
buffer; this value is stored in the integer whose address is given as 
the argument. 


Prints the address pointed to by. the argument in the form xxxx:yyyy, 
where xxxx is the segment and yyyy is the offset, and the digits x and 
y are uppercase hexadecimal digits; %hp indicates a near pointer 
and prints only the offset of the address. 
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Flag Directives 


The first optional field of the format specification is flag. A flag directive is a character 
that justifies output and prints signs, blanks, decimal points, and octal and hexadecimal pre- 
fixes. More than one flag directive may appear in a format specification. (See Table R.3.) 


Table R.3 Flag Characters for printf 


Flag 


blank (’) 


Meaning 


Left justify the result within the given 
field width. 


Prefix the output value with a sign 

(+ or —) if the output value is of a 
signed type. 

If width is prefixed with 0, zeros are 
added until the minimum width is 
reached. If 0 and — appear, the 0 is 
ignored. If 0 is specified with an 
integer format (i, u, x, X, 0, d), the 

0 is ignored. 

Prefix the output value with a blank if 
the output value is signed and positive; 
the blank is ignored if both the blank 
and + flags appear. 


When used with the o, x, or X format, 
the # flag prefixes any nonzero output 
value with 0, Ox, or OX, respectively. 


When used with the e, E, or f format, 


the # flag forces the output value to con- 


tain a decimal point in all cases. 


When used with the g or G format, the 
# flag forces the output value to contain 
a decimal point in all cases and pre- 
vents the truncation of trailing zeros. 


Ignored when used with ¢, d, i, u, ors. 


Default 


Right justify. 


Sign appears only for negative 
signed values (—). 


No padding. 


No blank appears. 


No blank appears. 


Decimal point appears only if 
digits follow it. 


Decimal point appears only if 
digits follow it. Trailing zeros are 
truncated. 
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Width Specification 


The second optional field of the format specification is the width specification. The width 
argument is a non-negative decimal integer controlling the minimum number of characters 
printed. If the number of characters in the output value is less than the specified width, 
blanks are added to the left or the right of the values—depending on whether the 

— flag (for left justification) is specified—until the minimum width is reached. If width is 
prefixed with 0, zeros are added until the minimum width is reached (not useful for left- 
justified numbers). 


The width specification never causes a value to be truncated. If the number of characters in 
the output value is greater than the specified width, or width is not given, all characters of 
the value are printed (subject to the precision specification). 


The width specification may be an asterisk (*), in which case an int argument from the 
argument list supplies the value. The width argument must precede the value being for- 
matted in the argument list. A nonexistent or small field width does not cause a truncation 
of a field; if the result of a conversion is wider than the field width, the field expands to 
contain the conversion result. 


Precision Specification 

The third optional field of the format specification is the precision specification. It speci- 
fies a non-negative decimal integer, preceded by a period (.), which specifies the number 
of characters to be printed, the number of decimal places, or the number of significant 
digits. (See Table R.4.) Unlike the width specification, the precision specification can 
cause truncation of the output value, or rounding in the case of a floating-point value. If 
precision is specified as zero and the value to be converted is zero, the result is no charac- 
ters output, as shown below: 


printf( "%.8d", @ ); /* No characters output */ 


The precision specification may be an asterisk (*), in which case an int argument from the 
argument list supplies the value. The precision argument must precede the value being for- 
matted in the argument list. 


The interpretation of the precision value and the default when precision is omitted depend 
on the type, as shown in Table R.4. 
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Table R.4 How printf Precision Values Affect Type 


Type 


“KOR ™ A 


ne qf 


Meaning 


The precision specifies the minimum num- 
ber of digits to be printed. If the number 
of digits in the argument is less than - 
precision, the output value is padded on 
the left with zeros. The value is not trun- 
cated when the number of digits exceeds 
precision. 


The precision specifies the number of 
digits to be printed after the decimal 
point. The last printed digit is rounded. 


The precision value specifies the number 
of digits after the decimal point. If a deci- 
mal point appears, at least one digit 
appears before it. The value is rounded to 
the appropriate number of digits. 


The precision specifies the maximum 
number of significant digits printed. 


The precision has no effect. 


The precision specifies the maximum 
number of characters to be printed. Char- 
acters in excess of precision are not 
printed. 


Default 


If precision is 0 or omitted entirely, or if 
the period (.) appears without a number 
following it, the precision is set to 1. 


Default precision is 6; if precision is 0 or 
the period (.) appears without a number 
following it, no decimal point is printed. 


Default precision is 6; if precision is 0, or 
if the period (.) appears without a number 
following it, no decimal point is printed. 


- Six significant digits are printed, with any 


trailing zeros truncated. 
Character is printed. 


Characters are printed until a null charac- 
ter is encountered. 


If the argument corresponding to a floating-point specifier is infinite, indefinite, or not a 
number (NAN), the printf function gives the following output: 


Value Output 

+ infinity 1.#INFrandom-digits 

— infinity ~—1#INFrandom-digits 
Indefinite digit #INDrandom-digits 
NAN digit #NANrandom-digits 
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Return Value 


Compatibility 


Size and Distance Specification 


For printf, the format specification fields F and N refer to the “distance” to the object 
being read (near or far), and h and | refer to the “size” of the object being read (16-bit 
short or 32-bit long). The following list clarifies this use of F, N, h, 1, and L: 


Program Code Action 

printf (" %Ns"); - Print near string 

printf (" %Fs"); Print far string 

_printf ("%Nn"); Store char count in near int 
printf ("%Fn"); Store char count in far int 
printf (" %hp"); Print a 16-bit pointer (xxxx) 
printf (" %lp"); Print a 32-bit pointer (xxx.xxx) 
printf (" %Nhn"); Store char count in near short int 
printf ("%Nin"); Store char count in near long int 
printf ("%Fhn"); Store char count in far short int 
printf (" %Fin"); Store char count in far int 


The specifications "%hs" and " %ls" are meaningless to printf. The specifications 
"JNp" and "%Fp" are aliases for" Z%hp" and " Z%lp" for the sake of compatibility with 
Microsoft C version 4.0, — 


The printf function returns the number of characters printed, or a negative value in the 
case of an error. 
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See Also fprintf, scanf, sprintf, vfprintf, vprintf, vsprintf 


Example 


/* PRINTF.C illustrates output formatting with printf. */ 
dFinclude <stdio.h> 


void main() 

{ 
char ch = th', *string = “computer”; 
int count = -9234; 
double fp = 251.7366; 


/* Display integers. */ 

printf( "Integer formats: \n" 
"\tDecimal: 2d Justified: %.6d Unsigned: Zu\n", 
count, count, count, count ); 


printf( "Decimal %d as:\n\tHex: %Xh C hex: @x%x Octal: %o0\n", 
count, count, count, count ); 


/* Display in different radixes. */ 
printf( "Digits 18 equal:\n\tHex: Zi Octal: %i Decimal: %i\n", 
@x1@, 018, 10 ); 


/* Display characters. */ 
printf( "Characters in field:\nZl@c %5c\n", ch, ch ); 


/* Display strings. */ 
printf( "Strings in field:\n%25s\n%25.4s\n", string, string ); 


/* Display real numbers. */ 
printf( “Real numbers:\n\taf bet %e ZE\n",. fp, fps. Toy: fps 


/* Display pointers. */ 
printf( "Address as:\n\tDefault: %p Near: 4Np Far: %Fp\n", 
&count, (int _near *)&count, (int _far *)&count ); 


/* Count characters printed. */ 

printf( "Display to here:\n" ); 

printf( "1234567890123456%n78901234567890\n", &count ); 
printf( "\tNumber displayed: Zd\n\n", count ); 
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Output 


Integer formats: 
Decimal: -9234 Justified: -@@9234 Unsigned: 56382 
Decimal -9234 as: 
Hex: DBEEh C hex: @xdbee Octal: 155756 
Digits 18 equal: 
Hex: 16 Octal: 8 Decimal: 10 
Characters in field: 
h h 
Strings in field: 
computer 
comp 
Real numbers: 
251.736600 251.74 2.517366e+082 2.517366E+002 
Address as: 
Default: 141C Near: 141C Far: @087:141C 
Display to here: 
123456789012345678901234567890 
Number displayed: 16 
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Description Writes a character to a stream (putc) or to stdout (putchar). 
#include <stdio.h> 


int putc( int c, FILE *stream ); 


int putchar( int c ); 


c Character to be written 
stream Pointer to FILE structure 
Remarks The pute routine writes the single character c to the output stream at the current position. 


The putchar routine is identical to putc(c, stdout). 


These routines are implemented as both macros and functions. See Section 1.4, “Choosing 
Between Functions and Macros,” for a discussion of how to select between the macro and 
function forms. . 


Return Value The pute and putchar routines return the character written, or EOF in the case of an error. 
Any integer can be passed to pute, but only the lower 8 bits are written. 


Compatibility MANS! M@ DOS W@ OS/2 UNIX MB XENIX 


See Also fputc, fputchar, getc, getchar 


Example 


/* PUTC.C: This program uses putc to write buffer to a stream. 
* If an error occurs, the program will stop before writing the 
* entire buffer. 

*/ 


dHinclude <stdio.h> 


void main() 

{ 
FILE *stream; 
char *p, buffer[] = "This is the line of output\n"; 
int ch; 
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/* Make standard out the stream and write to it. */ 

stream = stdout; 

for( p = buffer; (ch-!= EOF) && (*p != '\O'); p++ ) 
ch = putc( *p, stream ); 


Output 


This is the line of output 
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Description - Writes a character to the console. 
#include <conio.h> Required only for function declarations 
int putch( int c ); 
c Character to be output 
Remarks The putch function writes the character c directly (without buffering) to the console. 


Return Value The function returns c if successful, and EOF if not. 
Compatibility O ANS! @ DOS WM oOS/72 QO UNIX O XENIX 


See Also cprintf, getch, getche 


Example 


/* GETCH.C: This program reads characters from the keyboard until it 
* receives a 'Y' or ‘y',. 
*/ 


dtinclude <conio.h> 
#include <ctype.h> 


void main() 
int ch; 


cputs( "Type 'Y' when finished typing keys: " ); 


do 
{ 
ch = getch(); 
ch = toupper( ch ); 
} while( ch != 'Y' ); 
putch( ch ); 
putch( '\r' ); /* Carriage return */ 
putch( ‘\n’ ); /* Line feed Lf 
} 
Output 


Type 'Y' when finished typing keys: Y 


putenv 


592 


Description 


Remarks 


Return Value 


Creates new environment variables. 

#include <stdlib.h> Required only for function declarations 
int putenv( char “envstring ); 

envstring .  Environment-string definition 


The putenv function adds new environment variables or modifies the values of existing en- 
vironment variables. Environment variables define the environment in which a process ex- 
ecutes (for example, the default search path for libraries to be linked with a program). 


The envstring argument must be a pointer to a string with the form 
varname=string 


where varname is the name of the environment variable to be added or modified and string 
is the variable’s value. If varname is already part of the environment, its value is replaced 
by string; otherwise, the new varname variable and its string value are added to the en- 
vironment. A variable can be set to an empty value by specifying an empty string. 


This function affects only the environment that is local to the currently running process; it 
cannot be used to modify the command-level environment. When the currently running 
process terminates, the environment reverts to the level of the parent process (in most 
cases, the operating system level). However, the environment affected by putenv can be 
passed to any child processes created by spawn, exec, system, or (in OS/2 only) _popen, 
and these child processes get any new items added by putenv. 


Never free a pointer to an environment entry, because the environment variable will then 
point to freed space. A similar problem can occur if you pass putenv a pointer to a local 
variable, then exit the function in which the variable is declared. 


The putenv function operates only on data structures accessible to the run-time library and 
not on the environment “segment” created for a process by DOS or OS/2. 


Note that environment-table entries must not be changed directly. If an entry must be 
changed, use putenv. To modify the returned value without affecting the environment 
table, use strdup or strcpy to make a copy of the string. 


The getenv and putenv functions use the global variable environ to access the environ- 
ment table. The putenv function may change the value of environ, thus invalidating the 
envp argument to the main function. Therefore, it is safer to use the environ variable to 
access the environment information. 


The putenv function returns 0 if it is successful. A return value of —1 indicates an error. 


593 putenv 


Compatibiliy © O ANS! M DOS MOS? MM UNIX M@ XENIX 
See Also getenv 
Example 


/* GETENV.C: This program uses getenv to retrieve the LIB environment 
* variable and then uses putenv to change it to a new value. 
*/ 


fHinclude <stdlib.h> 
#Hinclude <stdio.h> 


main() 
{ 
char *libvar; 


/* Get the value of the LIB environment variable. */ 
libvar = getenv( "LIB" ); 
if( libvar != NULL ) 

printf( "Original LIB variable is: %s\n", libvar ); 


/* Attempt to change path. Note that this only affects the environment 
* variable of the current process. The command processor's environment 
* is not changed. 

*/ 
putenv( "LIB=c:\\mylib;c:\\yourlib" ); 


/* Get new value. */ 
libvar = getenv( “LIB" ); 
if( libvar != NULL ) 
printf( "New LIB variable is: %s\n", libvar ); 


Output 


Original LIB variable is: C:\LIB 
New LIB variable is: c:\mylib;c:\yourlib 
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Description 


Remarks 


Retrieve images from a buffer. 
#include <graph.h> 


void far putimage( short x, short y, char huge *image, short action ); 


void far _putimage_w( double wx, double wy, char _huge *image, short action ); 


x,y Position of upper-left corer of image 
image Stored image buffer 

action Interaction with existing screen image 
wx, wy Position of upper-left commer of image 


The _putimage function transfers to the screen the image stored in the buffer that image 
points to. 


In the _putimage function, the upper-left corner of the image is placed at the view coordi- 
nate point (x, y). In the _putimage_w function, the upper-left corner of the image is placed 
at the window coordinate point (wx, wy). 


The action argument defines the interaction between the stored image and the one that is 
already on the screen. It may be any one of the following manifest constants (defined in 
GRAPH.H): 


Constant Meaning 


_GAND Transfers the image over an existing image on the screen. The 
resulting image is the logical-AND product of the two images: 
points that had the same color in both the existing image and 
the new one will remain the same color, while points that have 
different colors are joined by logical-AND. 


_GOR Superimposes the image onto an existing image. The new 
image does not erase the previous screen contents. 


_GPRESET Transfers the data point-by-point onto the screen. Each point 
has the inverse of the color attribute it had when it was taken 
from the screen by _getimage, producing a negative image. 
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_GPSET Transfers the data point-by-point onto the screen. Each point 
has the exact color attribute it had when it was taken from the 
screen by _getimage. 


_GXOR Causes the points on the screen to be inverted where a point 
exists in the image buffer. This behavior is exactly like that of 
the cursor: when an image is put against a complex back- 
ground twice, the background is restored unchanged. This al- 
lows you to move an object around without erasing the 
background. The _GXOR constant is a special mode often 


used for animation. 
Return Value None. 
Compatibility O ANS! @ DOS OF 0S/2 QO UNIX O XENIX 
See Also '  _getimage, _imagesize 


Example See the example for _getimage. 


puts 


596 


Description 


Remarks 
Return Value 


Compatibility 
See Also 


Example 


Writes a string to stdout. 

#include <stdio.h> 

int puts( const char *string ); 

string String to be output 


The puts function writes string to the standard output stream stdout, replacing the string’s 
terminating null character (°\0’) with a newline character (\n) in the output stream. 


The puts function returns a nonnegative value if it is successful. If the function fails, it 
returns EOF. 


@ ANS! @ DOS WM OS/2 MW UNIX’ MW XENIX 


fputs, gets 


/* PUTS.C: This program uses puts to write a string to stdout. */ 


#Hinclude <stdio.h> 


void main() 


{ 


puts( “Hello world from puts!" ); 


} 


Output 


Hello world from puts! 
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Description Writes an integer to a stream. 
#include <stdio.h> 
int putw( int binint, FILE *stream ); 


binint Binary integer to be output 


stream Pointer to FILE structure 


Remarks The putw function writes a binary value of type int to the current position of stream. The 
putw function does not affect the alignment of items in the stream, nor does it assume any 
special alignment. 


The putw function is provided primarily for compatibility with previous libraries. Note 
that portability problems may occur with putw, since the size of an int and ordering of 
bytes within an int differ across systems. 


Return Value The putw function returns the value written. A return value of EOF may indicate an error. 
Since EOF is also a legitimate integer value, ferror should be used to verify an error. 


Compatibility O ANS| @ DOS MH OS/2 M@ UNIX @ XENIX 


See Also . getw 


Example 


/* PUTW.C: This program uses putw to write a word to a stream, 
* then performs an error check. 
x] 


#Hinclude <stdio.h> 
fHinclude <stdlib.h> 


void main() 

{ 
FILE *stream; 
unsigned u; 


if( (stream = fopen( "data.out", “wb" )) == NULL ) 
exit( 1 ); 
for€ u.= @; u < 10; ut+ ) 
{ 
putw( u + @x2132, stdout ); 
putw( u + @x2132, stream ); /* Write word to stream. */ 
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if( ferror( stream ) ) /* Make error check. */ 
{ 

printf( "“putw failed" ); 

clearerr( stream ); 

exit( 1 ); 
} 


} 
printf( "\nWrote ten words\n" ); 


fclose( stream ); 
} 


Output 


2IZI4ISIGI7IBI9OIs!;! 
Wrote ten words 
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Description Performs a quick sort. 

#include <stdlib.h> For ANSI compatibility 

#include <search.h> Required only for function declarations 

void qsort( void *base, size_t num, size_t width, 

int( *compare ) ( const void *elem/, const void *elem2 ) ); 

base Start of target array 

num Array size in elements 

width Element size in bytes 

compare Comparison function 

eleml Pointer to the key for the search 

elem2 Pointer to the array element to be compared with the key 
Remarks The qsort function implements a quick-sort algorithm to sort an array of num elements, 


each of width bytes. The argument base is a pointer to the base of the array to be sorted. _ 
The qsort function overwrites this array with the sorted elements. 


The argument compare is a pointer to a user-supplied routine that compares two array ele- 
ments and returns a value specifying their relationship. The qsort function calls the 
compare routine one or more times during the sort, passing pointers to two array elements 
on each call: 


compare( (void *) elem1, (void *) elem2 ); 


The routine must compare the elements, then return one of the following values: 


Value Meaning 

<0 elem! less than elem2 

=0 eleml equivalent to elem2 
>0 elem1 greater than elem2 


The array is sorted in increasing order, as defined by the comparison function. To sort an 
array in decreasing order, reverse the sense of “greater than” and “less than” in the com- 
parison function. 
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Return Value None. 

Compatibility @ ANS| & DOS & Os2 M UNIX @ XENIX 
See Also bsearch, Isearch 

Example 


/* QSORT.C: This program reads the command-line parameters and 
* uses qsort to sort them. It then displays the sorted arguments. 
x] 


#Hinclude <search.h> 
#Finclude <string.h> 
fHinclude <stdio.h> 


int compare( char **argl, char **arg2 ); /* Prototype */ 


void main( int argc, char **argv ) 
{ 
int i; 


/* Eliminate argv[@] from sort: */ 
argvt++; 
argc-; 


/* Sort remaining args using Quicksort algorithm: */ 
qsort( (void *)argv, (size_t)argc, sizeof( char * ), compare ); 


/* Output sorted list: */ 
for( i = @; i < argc; ++i ) 
printf( "%s ", argvli] ); 
printf( "\n" ); 
} 


int compare( char **argl, char **arg2 ) 

{ 4 
/* Compare all of both strings: */ 
return strempi( *argl, *arg2 ); 

} 


Output 


[C:\LIBREF] qsort every good boy deserves favor 
boy deserves every favor good 
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Description 


Remarks 


Sends a signal to the executing program. 


#include <signal.h> 
int raise( int sig ); 


sig 


The raise function sends sig to the executing program. If a signal-handling routine for sig 
has ben installed by a prior call to signal, raise causes that routine to be executed. If no 


Signal to be raised 


raise 


handler routine has been installed, the default action (as listed below) is taken. 


The signal value sig can be one of the following manifest constants: 


Signal 


SIGABRT 
SIGBREAK 
SIGFPE 


SIGILL 


SIGINT 
SIGSEGV 


SIGTERM 


SIGUSR1 
SIGUSR2 
SIGUSR3 


Meaning 


Abnormal termination. 
CTRL+ BREAK interrupt. 
Floating-point error. 


Illegal instruction. This signal 
is not generated by DOS or 
OS/2, but is supported for 
ANSI compatibility. 


CTRL+ C interrupt. 


Illegal storage access. This 
signal is not generated by 
DOS or OS/2, but is supported 
for ANSI compatiblity. 


Termination request sent to 
the program. This signal is not 
generated by DOS or OS/2, 
but is supported for ANSI 
compatibility. 


User-defined signals. 


Default 


Terminates the calling pro- 
gram with exit code 3. 


Terminates the calling pro- 
gram with exit code 3. 


Terminates the calling 
program. 


Terminates the calling 
program. 


Issues INT23H. 


Terminates the calling 
program. 


Ignores the signal. 


Ignores the signal. 
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Return Value If successful, the raise function returns 0. Otherwise, it returns a nonzero value. 
Compatibility MANS! 9 DOS HW OS2 O UNIX O XENIX 
See Also abort, signal 


Example See the example for signal. 


% 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


rand 


Generates a pseudorandom number. 
#include <stdlib.h> Required only for function declarations 
int rand( void ); 


The rand function returns a pseudorandom integer in the range 0 to RAND_MAX. The 
srand routine can be used to seed the pseudorandom-number generator before calling 
rand. 


The rand function returns a pseudorandom number, as described above. There is no error 
return. 


MANS! @ DOS HM OS/2 WM UNIX Mf XENIX 


srand 


/* RAND.C: This program seeds the random-number generator with the 
* time, then displays 28 random integers. 


aed 


#tinclude <stdlib.h> 
#include <stdio.h> 
#include <time.h> 


void main() 


{ 
int i; 


/* Seed the random-number generator with current time so that 


ey 


* the numbers will be different every time we run. 


srand( (unsigned)time( NULL ) ); 


/* Display 10 numbers. */ 
for( i = @; i < 10; i++ ) 
printf( " %6d\n", rand() ); 
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Output 


19471 
16395 

8268 
15582 

6489 
28356 
27842 

5276 
23070 
189308 
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Description Reads data from a file. ; 
#include <io.h> Required only for function declarations 
int read( int handle, void *buffer, unsigned int count ); 
handle Handle referring to open file 
buffer Storage location for data 
count Maximum number of bytes 
Remarks The read function attempts to read count bytes into buffer from the file associated with 


Return Value 


Compatibility 


handle. The read operation begins at the current position of the file pointer associated with 
the given file. After the read operation, the file pointer points to the next unread character. 


The read function returns the number of bytes actually read, which may be less than count 
if there are fewer than count bytes left in the file, or if the file was opened in text mode 
(see below). The return value 0 indicates an attempt to read at end-of-file. The return value 
—1 indicates an error, and errno is set to the following value: 


Value Meaning 

EBADF The given handle is invalid; or the file is not open for reading; 
or (DOS versions 3.0 and later and OS/2 only) the file is 
locked. 


If you are reading more than 32K (the maximum size for type int) from a file, the return 
value should be of type unsigned int (see the example that follows). However, the maxi- 
mum number of bytes that can be read from a file in one operation is 65,534, since 65,535 
(or OxFFFF) is indistinguishable from —1, and therefore cannot be distinguished from an 
error return. 


If the file was opened in text mode, the return value may not correspond to the number of 
bytes actually read. When text mode is in effect, each carriage-return—line-feed (CR-LF) 
pair is replaced with a single line-feed character. Only the single line-feed character is 
counted in the return value. The replacement does not affect the file pointer. 


Note that under DOS and OS/2, when files are opened in text mode, a CTRL+Z character is 
treated as an end-of-file indicator. When the CTRL+Z is encountered, the read terminates, 
and the next read returns 0 bytes. The Iseek function will clear the end-of-file indicator. 


O ANS! M@ DOS WM OS/2 WUNIX’ Mf XENIX 
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See Also creat, fread, open, write 


Example 


/* READ.C: This program opens a file named READ.C and tries to read 60,000 
* bytes from that file using read. It then displays the actual 

* number of bytes read from READ.C. 

*/ 


#Hinclude <fcntl.h> /* Needed only for O_RDWR definition */ 
#Hinclude <io.h> 

#Hinclude <stdlib.h> 

#Hinclude <stdio.h> 


char buffer[600200); 


void main() 
{ 
int fh; 
unsigned int nbytes = 60000, bytesread; 


/* Open file for input: */ 
if( (fh = open( "read.c", O_RDONLY )) == -1 ) 
( 
perror( “open failed on input file" ); 
exit( 1); 
} 
/* Read in input: */ 
if( ( bytesread = read( fh, buffer, nbytes ) ) <=@ ) 
perror( "Problem reading file" ); 
else 
printf( “Read Zu bytes from file\n", bytesread ); 


close( fh ); 


Output 


Read 747 bytes from file 
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realloc Functions 


Description 


Remarks 


Reallocate memory blocks. 


#include <stdlib.h> For ANSI compatibility (realloc only) 


#include <malloc.h> Required only for function declarations 


void *realloc( void *memblock, size_t size ); 


void _based( void ) *_brealloc( segment seg, void _based( void ) *memblock, 
size_t size ); 


void far * frealloc( void far *memblock, size_t size ); 


void near * nrealloc( void _near “memblock, size_t size ); 


memblock Pointer to previously allocated memory block 
size New size in bytes 


seg Segment selector 


The realloc family of functions changes the size of a previously allocated memory block. 
The memblock argument points to the beginning of the memory block. If memblock is 
NULL, realloc functions in the same way as malloc and allocates a new block of size 
bytes. If memblock is not NULL, it should be a pointer returned by calloc, malloc, or a 
prior call to realloc. 


The size argument gives the new size of the block, in bytes. The contents of the block are 
unchanged up to the shorter of the new and old sizes, although the new block may be ina 
different location. 


The memblock argument can also point to a block that has been freed, as long as there has 
been no intervening call to the corresponding calloc, malloc, expand, or realloc func- 
tion. If successful, the reallocated block is marked in use. 


In large data models (that is, compact-, large-, and huge-model programs), realloc maps to 
_frealloc. In small data models (tiny-, small-, and medium-model programs), realloc maps 
to_nrealloc. — . 
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The various realloc functions reallocate memory in the heap specified in the following list: 


Function Heap | 
realloc Depends on data model of program 
_brealloc Based heap specified by seg value 
_frealloc Far heap (outside default data segment) 
_nrealloc Near heap (inside default data segment) 
Return Value The realloc functions return a void pointer to the reallocated (and possibly moved) 
memory block. 


The return value is NULL if the size is zero and the buffer argument is not NULL, or if 
there is not enough available memory to expand the block to the given size. In the first 
case, the original block is freed. In the second, the original block is unchanged. 


The storage space pointed to by the return value is guaranteed to be suitably aligned for 
storage of any type of object. To get a pointer to a type other than void, use a type cast on 
the return value. 


Compatibility realloc 


MANS! M@ DOS HW OS/2 HW UNIX’ I XENIX 


_brealloc, _frealloc, _nrealloc 


O ANS! @ DOS WM OS/2 O UNIX OO XENIX 


See Also calloc functions, free functions, malloc functions 
Example 
/* REALLOC.C: This program allocates a block of memory for buffer 


* 
* 
* 
* 


*] 


and then uses _msize to display the size of that block. Next, it 
uses realloc to expand the amount of memory used by buffer 

and then calls _msize again to display the new amount of 

memory allocated to buffer. 
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dHinclude <stdio.h> 
dHinclude <malloc.h> 
#Hinclude <stdlib.h> 


void main() 

{ 
long *buffer; 
size_t size; 


if( (buffer = (long *)malloc( 1800 * sizeof( long ) )) == NULL ) 
exit( 1 ); 


size = _msize( buffer ); . 
printf( “Size of block after malloc of 1808 longs: %u\n", size ); 


/* Reallocate and show new size: */ 

if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) == NULL ) 
exit( 1 ); 

size = _msize( buffer ); 

printf( "Size of block after realloc of 1088 more longs: %u\n", size ); 


free( buffer ); 


Output 


Size of block after malloc of 1808 longs: 4000 
Size of block after realloc of 1080 more longs: 8000 
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Description 


Remarks 


Draw rectangles. 


- #include <graph.h> 


short far _rectangle( short control, short x/, short y/, short x2, short y2 ); 


short _far _rectangle_w( short control, double wx/, double wy/, double wx2, 
double wy2 ); 


short far _rectangle_wxy( short control, struct _wxycoord _far *pwxyl, 
struct _wxycoord far *pwxy2 ); 


control Fill flag 

xl, yl Upper-left corner 
x2, y2 Lower-right comer 
wxl, wyl Upper-left corner 
wx2, wy2 Lower-right comer 
pwxyl _ Upper-left corner 
pwxy2 . Lower-right comer 


The _rectangle functions draw a rectangle with the current line style. 


The _rectangle function uses the view coordinate system. The view coordinate points 
(x1, yl) and (x2, y2) are the diagonally opposed corners of the rectangle. 


The _rectangle_w function uses the window coordinate system. The window coordinate 
points (wx/, wy/) and (wx2, wy2) are the diagonally opposed corners of the rectangle. 


The rectangle _wxy function uses the window coordinate system. The window coordinate 
points (pwxy/) and (pwxy2) are the diagonally opposed corners of the rectangle. The 
coordinates for the __rectangle_wxy routine are given in terms of an_wxycoord structure 
(defined in GRAPH.H), which contains the following elements: 


Element Description 


double wx window .x coordinate 


double wy window y coordinate 
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_rectangle Functions 


Return Value 


Compatibility 


See Also 


Example 


The control parameter can be one of the following manifest constants: 


Constant Action 

_GFILLINTERIOR Fills the figure with the current color using the current fill 
mask 

_GBORDER Does not fill the rectangle 


If the current fill mask is NULL, no mask is used. Instead, the rectangle is filled with the 
current color. 


If you try to fill the rectangle with the _floodfill function, the rectangle must be bordered 
by a solid line-style pattern. 
The function returns a nonzero value if the rectangle is drawn successfully, or 0 if not. 


O ANS! @ DOS OF OS/7 OO UNIX OO XENIX 


_arc functions, _ellipse functions, _floodfill, _getcolor, _lineto functions, 
_pie functions, _setcolor, _setfillmask 


/* RECT.C: This program draws a rectangle. */ 


#Hinclude <conio.h> 
#Finclude <stdlib.h> 
#Hinclude <graph.h> 


void main() 


( 


) 


/* Find a val 


id graphics mode. */ 


if( !_setvideomode( _MAXRESMODE ) ) 


exit( 1 ); 


_rectangle( _GBORDER, 88, 50, 240, 150 ); 


getch(); 


_setvideomode( _DEFAULTMODE ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Initializes the fonts graphics system. 

#include <graph.h> 

short _far _registerfonts( unsigned char far *pathname ); 

pie: Path name specifying .FON files to be registered 


The _registerfonts function initializes the fonts graphics system. Font files must be 
registered with the _registerfonts function before any other font-related library function 
( getgtextextent, outgtext, setfont, unregisterfonts) can be used. 


The _registerfonts function reads the specified files and loads font header information 
into memory. Each font header takes up about 140 bytes of memory. 


The pathname argument is the path specification and file name of valid .FON files. The 
pathname can contain standard DOS wild-card characters. 


The font functions affect only the output from the font output function _outgtext; no other 
C run-time output functions are affected by font usage. 


The _registerfonts function returns a positive value which indicates the number of fonts 
successfully registered. A negative return value indicates failure. The following negative 
values may be returned: 


Value | Meaning 
—| No such file or directory. 
—2 One or more of the .FON files was not a 


valid, binary .FON file. 
3 One or more of the .FON files is damaged. 


O ANS! @ DOS OF OS7?2 O UNIX O XENIX 
_getfontinfo, _getgtextextent, _outgtext, _setfont, _unregisterfonts 


See the example for _outgtext. 
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Description 


Remarks 


_remapallpalette, _remappalette 


Remap all palette colors. 
#include <graph.h> 


short far _remapallpalette(long far *colors ); 


long far _remappalette( short index, long color ); 


colors Color value array 
index — Color index to reassign 
color _ Color value to assign color index to 


The _remapallpalette function remaps the entire color palette simultaneously to the colors 


. given in the colors array. The colors array is an array of long integers where the size of the 


array varies from 16 to 64 to 256, depending on the video mode. The number of colors 
mapped depends on the number of colors supported by the current video mode. The 
_remapallpalette function works in all video modes (except_ORESCOLOR mode), but 
only with EGA, MCGA, or VGA hardware. 


The default color values for a color text on 16-color graphics mode are shown below: 


Number Color Number Color 

0 Black : 8 Dark gray 

1 Blue 9 Light blue 

2 Green 10 Light green 

3 Cyan ll Light cyan 

4 Red 12 Light red 

5 Magenta 13 Light magenta 
6 Brown 14 Yellow 

7 White 15 Bright white 


The first array element specifies the new color value to be associated with color index 0 
(the background color in graphics modes). After the call to_remapallpalette, calls to 
_setcolor will index into the new array of colors. The mapping done by _remapallpalette 
affects the current display immediately. 
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The colors array can be larger than the number of colors supported by the current video 
mode, but only the first n elements are used, where 1 is the number of colors supported by 
the current video mode, as indicated by the numcolors element of the videoconfig 
structure. 


The long color value is defined by specifying three bytes of data representing the three 
component colors: red, green, and blue. 


Each of the three bytes represents the intensity of one of the red, green, or blue component 
colors, and must be in the range 0-31. In other words, the low-order six bits of each byte 
specify the component’s intensity and the high-order two bits should be zero. The fourth 
(high-order) byte in the long is unused and should be set to zero. The diagram below 
shows the ordering of bytes within the long value. 


For example, to create a lighter shade of blue, start with lots of blue, add some green, and 
maybe a little bit of red. The three-byte color value would be: 


blue byte green byte red byte 
00811111 @0181111 00011111 
high ————————————>_ low order 


Manifest constants are defined in GRAPH.H for the default color values corresponding to 
color indices 0-15 in color text modes and 16-color graphics modes, as shown below: 


Index Constant Index Constant 
0 _BLACK 8 _GRAY 
1 _BLUE 9 _LIGHTBLUE 
2 _GREEN 10 _LIGHTGREEN 
3 _CYAN 11 _LIGHTCYAN 
4 _RED 12 _LIGHTRED 
5 _MAGENTA 13 _LIGHTMAGENTA 
6 _BROWN 14 _YELLOW 
7 _WHITE 15 _BRIGHTWHITE 


The VGA supports a palette of 262,144 colors (256K) in color modes, and the EGA sup- 
ports a palette of only 64 different colors. Color values for EGA are specified in exactly 
the same way as with the VGA; however, the low-order four bits of each byte are simply 
ignored. 


The _remappalette function assigns a new color value color to the color index given by 
index. This remapping affects the current display immediately. 
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The _remappalette function works in all graphics modes, but only with EGA, MCGA, 
or VGA hardware. An error results if the function is called while using any other 
configuration. 


The color value used in_remappalette is defined and used exactly as noted above for 
_remapalipalette. The range of color indices used with _remappalette depends on the 
number of colors supported by the video mode. 


The _remapallpalette and_remappalette functions do not affect the presentation- 
graphics palettes, which are manipulated with the _pg getpalette, pg setpalette, and 
_pg_resetpalette functions. 


If a VGA or MCGA adapter is connected to an analog monochrome monitor, the color 
value is transformed into its gray-scale equivalent, based on the weighted sum of its red, 
green, and blue components (30% red + 50% green + 11% blue). The original red, green, 
and blue values are lost. 


Return Value If successful, _remapallpalette returns —1 (short). In case of an error, _remapallpalette 
returns 0 (short). 


If successful, remappalette returns the color value previously assigned to index, or —1 if 
the function is inoperative (not EGA, VGA, or MCGA), or if the color index is out of 
range. 


Note that _remapallpalette returns a short value and _remappalette returns a long value. 
Compatibility O ANS! M@ DOS OF 0s72 QO UNIX OC XENIX 
See Also _Selectpalette, _setbkcolor, _setvideomode 


Example 


/* RMPALPAL.C: This example illustrates functions for assigning 
* color values to color indices. Functions illustrated include: 
= _remappalette _remapallpalette 

* / 


#Finclude <graph.h> 
#Hinclude <conio.h> 
dHinclude <stdio.h> 
d#Finclude <stdlib.h> 


/* Macro for mixing Red, Green, and Blue elements of color */ 
#tdefine RGB(r,g,b) (((long) ((b) << 8 | (g)) << 8) | (r)) 
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long tmp, pal[256]; 
void main() 
{ 
short red, blue, green; 
short inc, i, mode, cells, xX, y, xinc, yinc; 
char buf({4@]; 
struct videoconfig vc; 


/* Make sure all palette numbers are valid. */ 
for( i = @; i < 256; i++ ) 
palCi] = _BLACK; 


/* Loop through each graphics mode that supports palettes. */ 
for( mode = _MRES4COLOR; mode <= _MRES256COLOR; mode++ ) 
{ 
if( mode == _ERESNOCOLOR ) 
modet++; 
if( !_setvideomode( mode ) ) 
continue; 


/* Set variables for each mode. */ 
_getvideoconfig( &vc ); 
switch( ve.numcolors ) 
{ 
case 256: /* Active bits in this order: */ 
cells = 13; . 
inc = 12; /* 22222222 2?2bbbbbb ??gggggg 2?rrrrrr */ 
break; 
case 16: 
cells = 4; 
if( (vc.mode == _ERESCOLOR) || (vc.mode == _VRES16COLOR) ) 
inc = 16; /* 22222222 ?2bb2???? 22?gg222? ??rr2?2?? = */ 
else 
inc = 32; /* 22222222 22Bb2?22? 22Gg?22?2? 22Rr222?2 = */ 
break; 
case 4; 
cells = 2; 
inc = 32; /* 22222222 22Bb222?? 22?Gg?222? 2?Rr222? = */ 
break; 
default: 
continue; 


x< 
—te 
a 
a 
uod 


vc.numxpixels / cells; 
vc.numypixels / cells; 
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/* Fill palette arrays in BGR order. */ 
for( i = @, blue = @; blue < 64; blue += inc ) 
for( green = @; green < 64; green += inc ) 
for( red = @; red < 64; red t= inc ) 
{ 7 
palfi] = RGB( red, green, blue ); 
/* Special case of using 6 bits to represent 16 colors. 
* If both bits are on for any color, intensity is set. 
* If one bit is set for a color, the color is on. 
aif 
if( inc == 32 ) 
palCi + 8) = palli] | (palfli] >> 1); 
j++; 


} 


/* If palettes available, remap all palettes at once. */ 
if( !_remapallpalette( pal ) ) 
( 
_setvideomode( _DEFAULTMODE ); 
_outtext( “Palettes not available with this adapter" ); 
exit( 1 ); 
} 


/* Draw colored squares. */ 
for (4 =O, k= Oe * <-C MING: * COlls ys. k-4— Kine) 
for( y = 6s y < ( yine * cells); y t= yinc ) 
{ 
_setcolor( i++ ); . 
_rectangle( _GFILLINTERIOR, x, y, x + xinc, y + yinc ); 
} 


/* Note that for 256-color mode, not all colors are shown. The number 
* of colors from mixing three base colors can never be the same as 
* the number that can be shown on a two-dimensional grid. 
* / ‘ 
sprintf( buf, “Mode %d has %d colors", vc.mode, vc.numcolors ); 
_setcolor( vc.numcolors / 2 ); 
_outtext( buf ); 
getch(); 
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/* Change each palette entry separately in GRB order. */ 
for( i = @, green = @; green < 64; green += inc ) 
for( red = @; red < 64; red += inc ) 
for(blue = @; blue < 64; blue += inc ) 
{ 
tmp = RGB( red, green, blue ); 
_remappalette( i, tmp ); 
-if( ine == 32 ) 
_remappalette( i + 8, tmp | (tmp >> 1) ); 
jtt;. 
} 
getch(); 
} 
_setvideomode( _DEFAULTMODE ); 
} 
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Description Deletes a file. 
#include <stdio.h> Required for ANSI compatibility 
#include <io.h> Use either IO.H or STDIO.H 


int remove( const char *path ); 


path Path name of file to be removed 
Remarks The remove function deletes the file specified by path. 
Return Value The function returns 0 if the file is successfully deleted. Otherwise, it returns —1 and sets 


errno to one of these values: 


Value Meaning 
EACCES Path name specifies a read-only file. 
ENOENT File or path name not found, or path name specifies a 
directory. 
Compatibility MANS! @ DOS #8 OS O UNIX OO XENIX 
See Also unlink 


Example 
/* REMOVE.C: This program uses remove to delete REMOVE.OBJ. */ 
#Hinclude <stdio.h> 
void main() 
| if( remove( “remove.obj" ) == -1 ) 
perror( "Could not delete 'REMOVE.OBJ'" ); 


else 
printf( “Deleted 'REMOVE.OBJ'\n" ); 


Output 


Deleted *REMOVE.OBJ' 
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Description 


Remarks — 


Return Value 


Compatibility 


Example 


Renames a file or directory. 


#include <stdio.h> Required for ANSI compatibility 
#include <io.h> Use either IO.H or STDIO.H 


int rename( const char “oldname, const char *newname )3 


oldname Pointer to old name 


newname Pointer to new name 


The rename function renames the file or directory specified by oldname to the name given 
by newname. The old name must be the path name of an existing file or directory. The new 
name must not be the name of an existing file or directory. 


The rename function can be used to move a file from one directory to another by giving a 
different path name in the newname argument. However, files cannot be moved from one 
device to another (for example, from drive A to drive B). Directories can only be renamed, 
not moved. : 


The rename function returns 0 if it is successful. On an error, it returns a nonzero value 
and sets errno to one of the following values: 


Value Meaning 


EACCES File or directory specified by newname already exists or could 
not be created (invalid path); or oldname is a directory and 
newname specifies a different path. 


ENOENT File or path name specified by oldname not found. 


EXDEV Attempt to move a file to a different device. 


MANS! M@ DOS HM OS2 OF UNIX O XENIX 


/* RENAMER.C: This program attempts to rename a file named RENAMER.OBJ to 
* RENAMER.JBO. For this operation to succeed, a file named RENAMER.OBJ 
* must exist and a file named RENAMER.JBO must not exist. 


bal 


#include <stdio.h> 
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void main() 
{ 
int result; 
char old{[] = "RENAMER.OBJ", new{] = “RENAMER.JBO"; 


/* Attempt to rename file: */ 
result = rename( old, new ); 
if( result != @ ) 
printf( "Could not rename '%s'\n", old ); 
else 
printf( "File '%s' renamed to ‘%s'\n", old, new ); 


Output 


File 'RENAMER.OBJ' renamed to "RENAMER.JBO' 
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Description 


Remarks 


Return Value 
Compatibility 


Example 


Repositions the file pointer to the beginning of a file. 
#include <stdio.h> 

void rewind( FILE *stream ); 

stream Pointer to FILE structure 


The rewind function repositions the file pointer associated with stream to the beginning of 
the file. A call to rewind is equivalent to 


(void) fseek( stream, 0L, SEEK_SET ); 


except that rewind clears the error indicators for the stream, and fseek does not. Both 
rewind and fseek clear the end-of-file indicator. Also, fseek returns a value that indicates 
whether the pointer was successfully moved, but rewind does not return any value. 


You can also use the rewind function to clear the keyboard buffer. Use the rewind func- 
tion with the stream stdin, which is associated with the keyboard by default. 


The rewind function has no return value. 


Mm ANS| M@ DOS MOS? MM UNIX. M@ XENIX 


/* REWIND.C: This program first opens a file named REWIND.OUT for input and 
* output and writes two integers to the file. Next, it uses rewind to 

* reposition the file pointer to the beginning of the file and reads 

* the data back in. 


ef 


dFinclude <stdio.h> 


void main() 
{ 


FILE *stream; 
int datal, data2; 


datal = 1; 
data2 


if( (stream 
{ 
fprintf( 


-37; 


= fopen( "rewind.out", "wt" )) != NULL ) 


stream, "%d 4d", datal, data2 ); 


printf( "The values written are: 4d and %d\n", datal, data2 ); 
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rewind( stream ); 

fscanf( stream, "%d 4d", &datal, &data2 ); 

printf( "The values read are: %d and %d\n", datal, data2 ); 
fclose( stream ); 


Output 


The values written are: 1 and -37 
The values read are: 1 and -37 
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Description Deletes a directory. 
#include <direct.h> Required only for function declarations 
int rmdir( char *dirname ); 
dirname Path name of directory to be removed 
Remarks The rmdir function deletes the directory specified by dirname. The directory must be 
empty, and it must not be the current working directory or the root directory. 
Return Value The rmdir function returns the value 0 if the directory is successfully deleted. A return 
value of —1 indicates an error, and errno is set to one of the following values: 
Value Meaning 
EACCES The given path name is not a directory; or the directory is not 
empty; or the directory is the current working directory or the 
root directory. 
ENOENT Path name not found. 
Compatibility O ANS! @ DOS WM OS/2 OF UNIX OO XENIX 
See Also chdir, mkdir 
Example 


/* MAKEDIR.C */ 


dFinclude <direct.h> 
dHinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main() 
{ 
int result; 
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if( mkdir( "“\\testtmp" ) == @ ) 


( 
printf( "Directory ‘'\\testtmp' was successfully created\n" ); 


system( “dir \\testtmp" ); 
if( rmdir( "\\testtmp" ) == @ ) 

printf( “Directory '\\testtmp' was successfully removed\n" ); 
else 

printf( “Problem removing directory '\\testtmp'\n" ); 


} 
else 
printf( "Problem creating directory ‘\\testtmp'\n" ); 


Output 


Directory ‘'\testtmp' was successfully created 


The volume label in drive C is 082. 
Directory of C:\TESTTMP 


<DIR> 6-19-89 11:20a 
<DIR> 6-19-89 11:28a 
2 File(s) 12730368 bytes free 
Directory '\testtmp’ was successfully removed 
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Description Removes temporary files. 
#include <stdio.h> 
int rmtmp( void ); 


Remarks The rmtmp function is used to clean up all the temporary files in the current directory. 
The function removes only those files created by tmpfile and should be used only in the 
same directory in which the temporary files were created. 


Return Value The rmtmp function returns the number of temporary files closed and deleted. 
Compatibility O ANS! @& DOS H OS/2 MW UNIX MM XENIX 

See Also flushall, tmpfile, tmpnam 

Example 


/* TMPFILE.C: This program uses tmpfile to create a temporary file, 
* then deletes this file with rmtmp. 
of 


_#include <stdio.h> 


void main() 

{ 
FILE *stream; 
char tempstring[] = "String to be written"; 
int i; 


/* Create temporary files. */ 
for( i = 1; i <= 10; i++ ) 
{ 
if( (stream = tmpfile()) == NULL ) 

perror( "Could not open new temporary file\n" ); 
else 

printf( "Temporary file %d was created\n", i ); 
} % 


/* Remove temporary files. */ 
printf( "%d temporary files deleted\n", rmtmp() ); 


627 | rmtmp 


Output 


was created 
was created 


Temporary file l 

Temporary file 2 

Temporary file 3 was created 
Temporary file 4 was created 
Temporary file 5 was created 
Temporary file 6 was created 
Temporary file 7 was created 
Temporary file 8 was created 
Temporary file 9 was created 
Temporary file 10 was created 
1@ temporary files deleted 
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Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


Rotate bits to the left (_rotl) or right (_rotr). 
#include <stdlib.h> 


unsigned int _rotl( unsigned int value, int shift ); 


unsigned int _rotr( unsigned int value, int shift ); 


value Value to be rotated 


shift Number of bits to shift 


The _rotl and _rotr functions rotate the unsigned value by shift bits. The _rotl function 
rotates the value left. The _rotr function rotates the value right. Both functions “wrap” bits 
rotated off one end of value to the other end. 


Both functions return the rotated value. There is no error return. 
CO ANS! @ DOS Wf OS/72 OF UNIX O XENIX 
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/* ROT.C: This program uses _rotr and _rotl with different shift 
* values to rotate an integer. 


mf 


#Hinclude <stdlib.h> 
#include <stdio.h> 


void main() 


( 


unsigned val = @x@fd93; 


printf( "@x%4.4x rotated left three times is Ox%4.4x\n", 


val, 


_rotl( val, 3) ); 


printf ( "@x%4.4x rotated right four times is @x%4.4x\n", 
val, _rotr( val, 4 ) ); 


629 _rotl, _rotr 


Output 


O@xfd93 rotated left three times is @xec9f 
Oxfd93 rotated right four times is Ox3fd9 


scant 
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Description 


Remarks 


Reads formatted data from the standard input stream. 
#include <stdio.h> 
int scanf( const char *format [,argument]... ); | 


format Format control 


argument Optional argument 


The scanf function reads data from the standard input stream stdin into the locations given 
by argument. Each argument must be a pointer to a variable with a type that corresponds 
to a type specifier in format. The format controls the interpretation of the input fields. The 
format can contain one or more of the following: 


m™ White-space characters: blank (’ ’); tab (\t); or newline (\n). A white-space character 
causes scanf to read, but not store, all consecutive white-space characters in the input 
up to the next non-white-space character. One white-space character in the format 
matches any number (including 0) and combination of white-space characters in the 
input. 


m@ Non-white-space characters, except for the percent sign (%). A non-white-space char- 
acter causes scanf to read, but not store, a matching non-white-space character. If the 
next character in stdin does not match, scanf terminates. 


m@ Format specifications, introduced by the percent sign (%). A format specification 
causes scanf to read and convert characters in the input into values of a specified type. 
The value is assigned to an argument in the argument list. 


The format is read from left to right. Characters outside format specifications are expected 
to match the sequence of characters in stdin; the matching characters in stdin are scanned 
but not stored. If a character in stdin conflicts with the format specification, scanf termi- 
nates. The character is left in stdin as if it had not been read. 


When the first format specification is encountered, the value of the first input field is con- 
verted according to this specification and stored in the location that is specified by the first 
argument. The second format specification causes the second input field to be converted 
and stored in the second argument, and so on through the end of the format string. 


An input field is defined as all characters up to the first white-space character (space, tab, 
or newline), or up to the first character that cannot be converted according to the format 
specification, or until the field width (if specified) is reached. If there are too many argu- 
ments for the given specifications, the extra arguments are evaluated but ignored. The re- 
sults are unpredictable if there are not enough arguments for the format specification. 
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A format specification has the following form: 


%o(l* 1 [width] [(F 1N}] L{h 11} Itype 


Each field of the format specification is a single character or a number signifying a particu- 
lar format option. The type character, which appears after the last optional format field, de- 
termines whether the input field is interpreted as a character, a string, or a number. The 
simplest format specification contains only the percent sign and a type character (for ex- 
ample, 4s ). 


- Each field of the format specification is discussed in detail below. If a percent sign (%) is 
followed by a character that has no meaning as a format-control character, that character 
and the following characters (up to the next percent sign) are treated as an ordinary 
sequence of characters—that is, a sequence of characters that must match the input. For ex- 
ample, to specify that a percent-sign character is to be input, use %2. 


An asterisk (*) following the percent sign suppresses assignment of the next input field, 
which is interpreted as a field of the specified type. The field is scanned but not stored. 


The width is a positive decimal integer controlling the maximum number of characters to 
be read from stdin. No more than width characters are converted and stored at the corre- 
sponding argument. Fewer than width characters may be read if a white-space character 
(space, tab, or newline) or a character that cannot be converted according to the given for- 
mat occurs before width is reached. 


The optional F and N prefixes allow the user to specify whether the argument is far or 

near, respectively. F should be prefixed to an argument pointing to a far object, while N 
should be prefixed to an argument pointing to a near object. Note also that the F and N pre- 
fixes are not part of the ANSI definition for scanf, but are instead Microsoft extensions, 
which should not be used when ANSI portability is desired. 


The optional prefix | indicates that the long version of the following type is to be used, 
while the prefix h indicates that the short version is to be used. The corresponding 
argument should point to a long or double object (with the I character) or a short object 
(with the h character). The 1 and h modifiers can be used with the d, i, n, 0, x, and u type 
characters. The | modifier can also be used with the e, f, and g type characters. The 1 and h 
modifiers are ignored if specified for any other type. 


For scanf, N and F refer to the “distance” to the object being read in (near or far) and h 
and I refer to the “size” of the object being read in (16-bit short or 32-bit long). The list 
below clarifies this use of N, F, 1, and h: 
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Program Code Action 

scanf("%Ns", &X );— - Read a string into near memory 
scanf("%Fs", &X ); Read a string into far memory 
scanf( "%Nd", &x ); Read an int into near memory 
scanf( "%Fd", &x ); Read an int into far memory 


scanf( "%2Nld", &x 
scanf( "%Fld", &x 


ye Read a long int into near memory 
); 
scanf( ""%Nhp", &x ); Read a 16-bit pointer into near memory 
); 
); 
); 


Read a long int into far memory 


scanf("%N1p", &x 
scanf( "%Fhp", &x 
scanf( "%F1lp", &x 


Read a 32-bit pointer into near memory 
Read a 16-bit pointer into far memory 


Read a 32-bit pointer into far memory 


The type characters and their meanings are described in Table R.5. 


To read strings not delimited by space characters, a set of characters in brackets ([ ]) can 
be substituted for the s (string) type character. The corresponding input field is read up to 
the first character that does not appear in the bracketed character set. If the first character 
in the set is a caret (4), the effect is reversed: the input field is read up to the first character 
that does appear in the rest of the character set. 


Note that %[a-z] and %[z-a] are interpreted as equivalent to %[abcde...z]. This is a com- 
mon scanf extension, but note that it is not required by the ANSI specification. 


To store a string without storing a terminating null character (’\0’), use the specification 
Yonc, where n is a decimal integer. In this case, the c type character indicates that the argu- 
ment is a pointer to a character array. The next n characters are read from the input stream 
into the specified location, and no null character (’\0’) is appended. If n is not specified, the 
default value for it is 1. 


The scanf function scans each input field, character by character. It may stop reading a par- 
ticular input field before it reaches a space character for a variety of reasons: the specified 
7 width has been reached; the next character cannot be converted as specified; the next char- 
acter conflicts with a character in the control string that it is supposed to match; or the next 

character fails to appear in a given character set. For whatever reason, when scanf stops 
reading an input field, the next input field is considered to begin at the first unread charac- 
ter. The conflicting character, if there is one, is considered unread and is the first character 
of the next input field or the first character in subsequent read operations on stdin. 
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Return Value 


scanf 


Table R.5 Type Characters for scanf 

Character Type of Input Expected Type of Argument 

d Decimal integer Pointer to int 

0 Octal integer Pointer to int 

x Hexadecimal integer! Pointer to int 

i Decimal, hexadecimal, or octal in- Pointer to int 

teger 

u Unsigned decimal integer Pointer to unsigned int 

U Unsigned decimal integer Pointer to unsigned long 

e, E Floating-point value consisting of Pointer to float 

f an optional sign (+ or—), a series of 

£,G one or more decimal digits contain- 

ing a decimal point, and an optional 
exponent (“e” or “E”) followed by 
an optionally signed integer value. 

c Character. White-space characters Pointer to char 

that are ordinarily skipped are read 
when ¢ is specified; to read the next 
non-white-space character, use %1s. 

S String Pointer to character array large 
enough for input field plus a termi- 
nating null character (’\0’), which is 
automatically appended. 

n No input read from stream or buffer. Pointer to int, into which is stored 
the number of characters success- 
fully read from the stream or buffer 
up to that point in the current call to 
scanf. 

P Value in the form xxxv:yyyy, where Pointer to far pointer to void 


the digits x and y are uppercase hex- 
adecimal digits. 


1 Since the input for a %x format specifier is always interpreted as a hexadecimal number, the input should 
not include a leading Ox. (If Ox is included, the 0 is interpreted as a hexadecimal input value.) 


The scanf function returns the number of fields that were successfully converted and as- 
signed. The return value may be less than the number requested in the call to scanf. The re- 
turn value does not include fields that were read but not assigned. 


The return value is EOF if the end-of-file or end-of-string is encountered in the first at- 
tempt to read a character. 
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Compatibility MANS! @ DOS 8 OS/72 W@W UNIX = XENIX 
See Also fscanf, printf, sscanf, vfprintf, vprintf, vsprintf 
Example 


/* SCANF.C: This program receives formatted input using scanf. */ 
#include <stdio.h> 


void main() 
{ 
int i; 
float fp; 
char c, s({8l1J; 
int result; 


printf( "Enter an integer, a floating-point number, " 
“a character and a string:\n" ); 
result = scanf( "4d %2f %c 4s", &i, &fp, &c, s ); 


printf( "\nThe number of fields input is %d\n", result ); 
printf( "The contents are: 4d *f 4c %s\n", i, fp, c, Ss ); 


Output 


Enter an integer, a floating-point number, a character and a string: 
71 ; 

98.6 

h 

White space stops input 


The number of fields input is 4 
The contents are: 71 98.599998 h White 
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Description Scrolls the text in a text window. 
#include <graph.h> 
void far _scrolltextwindow( short lines ); 
lines Number of lines to scroll 


Remarks The _scrolltextwindow function scrolls the text in a text window (previously defined by 
the _settextwindow function). The /ines argument specifies the number of lines to scroll. 
A positive value of Jines scrolls the window up (the usual direction); a negative value 
scrolls the window down. Specifying a number larger than the height of the current text 
window is equivalent to calling _clearscreen(_GWINDOW ). A value of 0 for lines has no 
effect on the text. 


Return Value None. 
Compatibility O ANS! @ DOS WOS/2 QO UNIX O XENIX 
See Also _gettextposition, outmem, _outtext, settextposition, _settextwindow 


Example 


/* SCRIXWIN.C: This program displays text in text windows and then 
* scrolls, inserts, and deletes lines.’ 
| 


dHinclude <stdio.h> 
dFinclude <conio.h> 
#include <graph.h> 


void deleteline( void ); 
void insertline( void ); 
void status( char *msg ); 


void main() 

{ 
short row; 
char buf[4@]; 


Le Set up screen for scrolling, and put text window around scroll area. */ 
_settextrows( 25 ); 
_Clearscreen( _GCLEARSCREEN ); 
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for( row = 1; row <= 25; rowt+ ) 

{ 
_settextposition( row, 1 ); 
sprintf( buf, “Line %c 220°; row + *A’ = 1, row )¢ 
_outtext( buf ); 

} 

getch(); 

_settextwindow( 1, 1, 25, 10 ); 


/* Delete some lines. */ 

_settextposition( 11, i ); 

for( row = 12; row < 20; rowtt+ ) 
deleteline(); 

Status( "Deleted 8 lines" ); 


/* Insert some lines. */ 

_settextposition( 5, 1 ); 

for( row = 1; row < 63 rowt+t ) 
insertline(); 

status( “Inserted 5 lines" ); 


/* Scroll] up and down. */ 
_scrolltextwindow( -7 ); 
status( "Scrolled down 7 lines" ); 
_scrolltextwindow( 5 ); 
status( "Scrolled up 5 lines" ); 
_setvideomode( _DEFAULTMODE ); 

} 


/* Delete lines by scrolling them off the top of the current text window. 
* Save and restore original window. 
*/ 
void deleteline() 
{ 
short left, top, right, bottom; 
struct rccoord rc; 


_gettextwindow( &top, &left, &bottom, &right ); 
re = _gettextposition(); 

-settextwindow( rc.row, left, bottom, right ); 
_scrolltextwindow( _GSCROLLUP ); 
_settextwindow( top, left, bottom, right ); 
_settextposition( rc.row, rc.col ); 
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/* Insert some lines by scrolling in blank lines from the top of the 
* current text window. Save and restore original window. 
*/ 
void insertline() 
{ 
short left, top, right, bottom; 
struct rccoord rc; 


_gettextwindow( &top, &left, &bottom, &right ); 
re = _gettextposition(); 
_settextwindow( rc.row, left, bottom, right ); 
_scrolltextwindow( _GSCROLLDOWN ); 
_settextwindow( top, left, bottom, right ); 
_settextposition( rc.row, rc.col ); 

) 


/* Display and clear status in its own window. */ 
void status( char *msg ) 
{ 

short left, top, right, bottom; 

struct rccoord rc; 


_gettextwindow( &top, &left, &bottom, &right ); 
_settextwindow( 1, 50, 2, 88 ); 

_outtext( msg ); 

getch(); 

_clearscreen( _GWINDOW ); 

_settextwindow( top, left, bottom, right ); 
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Description Searches for a file using environment paths. 
#include <stdlib.h> 


void searchenv( char *filename, char *varname, char *pathname ); 


filename Name of file to search for 
varname Environment to search 
pathname Buffer to store complete path 
Remarks The _searchenv routine searches for the target file in the specified domain. The varname 


variable can be any environment variable which specifies a list of directory paths, such as 
PATH, LIB, INCLUDE, or other user-defined variables. It is most often PATH, which 
searches for filename on all paths specified in the PATH variable. The _searchenv func- 
tion is case-sensitive, so the varname variable should match the case of the environment 
variable. 


The routine first searches for the file in the current working directory. If it doesn’t find the 
file, it next looks through the directories specified by the environment variable. 


If the target file is found in one of the directories, the newly created path is copied into the 
buffer pointed to by pathname. You must ensure that there is sufficient space for the con- 
structed path name. If the filename file is not found, pathname will contain an empty null- 


terminated string. 
Return Value The _searchenvy function does not return a value. 
Compatibility O ANS| @ DOS HM OS OO UNIX O XENIX 
See Also getenv, putenv | 


Example 


/* SEARCHEN.C: This program searches for a file in a directory 
* specified by an environment variable. 
74 


#tinclude <stdlib.h> 
dFinclude <stdio.h> 
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void main() 
{ 
char pathbuffer[_MAX_PATH]; 
char searchfile{] = "CL.EXE"; 
char envvar[] = "PATH"; 
/* Search for file in PATH environment variable: */ 
_searchenv( searchfile, envvar, pathbuffer ); 
if( *pathbuffer != '\@' ) 
printf( "Path for %s: %s\n", searchfile, pathbuffer ); 
else 
printf( "%s not found\n", searchfile ); 


Output 


Path for CL.EXE: C:\BIN\CL.EXE 
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EN SIT 
Description Gets the current values of segment registers. 

#include <dos.h> 

void segread( struct SREGS *segregs ); 

Segregs Segment-register values 


Remarks The segread function fills the structure pointed to by segregs with the current contents of 
the segment registers. The SREGS union is described in the reference section for int86x. 
This function is intended to be used with the intdosx and int86x functions to retrieve 
segment-register values for later use. 


Return Value None. 
Compatibility O ANS! MH DOS WW OS/72 O UNIX OO XENIX 
See Also FP_SEG, intdosx, int86x 


Example 
/* SEGREAD.C: This program gets the current segment values with segread. */ 


d#Finclude <dos.h> 
#finclude <stdio.h> 


void main() 

{ 
struct SREGS segregs; 
unsigned cs, ds, es, SS; 


/* Read the segment register values */ 
segread( &segregs ); 


cs = segregs.cs; 
ds = segregs.ds; 
es = segregs.es; 
SS = segregs.ss; 


printf( "CS = Ox%.4x DS = 0x%.4x ES = 0x%.4x SS = Ox%.4x\n", 
Cs -ds, 69. SS") s~ : 
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Output 
CS = 0x@047 DS = 9x@967 ES = @xQ®67 SS = 0x8067 


CS = @x2bcc OS = Ox2ce8 ES = @x2ba3 SS = O@x2ce8 
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Description 


Remarks 


Selects a graphics palette. 

#include <graph.h> 

short far _selectpalette( short number ); 
number Palette number 


The _selectpalette function works only under the video modes _MRES4COLOR and 
_MRESNOCOLOR. A palette consists of a selectable background color (Color 0) and three 
set colors. Under the MRES4COLOR mode, the number argument selects one of the four 
predefined palettes shown in Table R.6. 


Table R.6 | |MRES4COLOR Palette Colors 


Color Index 
Palette Number Color 1 Color2 Color3 
0 _ Green | Red Brown | 
1 Cyan Magenta Light 
gray 
Light green Light red Yellow 
3 Light cyan Light magenta White 


The _MRESNOCOLOR video mode is used with black-and-white displays, producing 
palettes consisting of various shades of gray. It will also produce color when used with a 
color display. The number of palettes available depends upon whether a CGA or EGA 
hardware package is employed. Under a CGA configuration, only the two palettes shown 
in Table R.7 are available. 


Table R.7_ _MRESNOCOLOR Mode CGA Palette Colors 


Color Index 
Palette Number -Colorl Color2 Color 3 
0 Blue Red Light 


gray 
1 Light blue Light red White 
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Under the EGA configuration, the three palettes shown in Table R.8 are available in the 
_MRESNOCOLOR video mode. 


Table R.8 |MRESNOCOLOR Mode EGA Palette Colors 


Color Index 
Palette Number Color1 Color2 Color3 
0 Green Red Brown 
l Light green Light red Yellow 
2 Light cyan Light red Yellow 


Note that with an EGA in _MRESNOCOLOR video mode, Palette 3 is identical to 


Palette 1. 
Return Value The function returns the value of the previous palette. There is no error return. 
Compatibility O ANS! M@ DOS OF OS/ QO UNIX OC XENIX 
See Also _getvideoconfig, _setbkcolor, _setvideomode 


Example 
/* SELPAL.C: This program changes the current CGA palette. */ 


dHinclude <stdio.h> 
#Hinclude <stdlib.h> 
dHinclude <conio.h> 
#Hinclude <graph.h> 


long bkcolor[8] = { _BLACK, _BLUE, GREEN, _CYAN, 
2RED; MAGENTA, _BROWN, _WHITE }; 
char *bkname [] = ( "BLACK", "BLUE", "GREEN", "CYAN", 


*"RED™; "MAGENTA", "BROWN", “WHITE” };- 
void main() 
{ 
fhte 15. ks 


if ( !_setvideomode( _MRES4COLOR ) ) 
{ 
printf( "No palettes available” ); 
exit( 1 ); 
} 
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for( i = @; i < 4; i++ ) /* Palette loop */ 
{ 
_selectpalette( i ); 
for( k = 0; k < 8; k++ ) /* Background color loop */ 
{ 
_Clearscreen( _GCLEARSCREEN ); 
_setbkcolor( bkcolor[k] ); 
_settextposition( 1, 1 ); 
printf( "Background: %s\tPalette: %d", bknameCk], i ); 
for( j = 1; j < 43 j++) /* Foreground color loop */ 
{ 
_setcolor( j ); 
_ellipse( _GFILLINTERIOR, 100, j * 30, 220, 80 + (j * 30) ); 
} ‘ 
getch(); 
} 
} 
_setvideomode( _DEFAULTMODE ); 
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a Ei ELE 
Description Sets the active page. 

#include <graph.h> 

short far _setactivepage( short page ); 

page Memory page number 


Remarks For hardware and mode configurations with enough memory to support multiple screen 
pages, _setactivepage specifies the area in memory in which graphics output is written. 
The page argument selects the current active page. The default page number is 0. 


Screen animation can be done by alternating the graphics pages displayed. Use the 
_setvisualpage function to display a completed graphics page while executing graphics 
statements in another active page. 


These functions can also be used to control text output if you use the text functions 
_gettextcursor, settextcursor, outtext, settextposition, _gettextposition, 
_settextcolor, _gettextcolor, _settextwindow, and _wrapon instead of the standard 
C-language I/O functions. 


The CGA hardware configuration has only 16K of RAM available to support multiple 
video pages, and only in the text mode. The EGA and VGA configurations may be 
equipped with up to 256K of RAM for multiple video pages in graphics mode. 


Return Value If successful, the function returns the page number of the Preyieus active page. If the func- 
tion fails, it returns a negative value. 


Compatibility O ANSI! W@ DOS OF OS/2 O UNIX OO XENIX 
See Also _getactivepage, _getvisualpage, _setvisualpage 
Example 
/* PAGE.C illustrates video page functions including: 
* _getactivepage _getvisualpage _setactivepage -_setvisualpage 
*/ : 


#Finclude <conio.h> 
#Hinclude <graph.h> 
#include <stdlib.h> 
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void main() 


{ 


} 


short oldvpage, oldapage, page, row, col, line; 
struct videoconfig vc; 
char  buf{[8Q); 


_getvideoconfig( &vc ); 
if( ve.numvideopages < 4 ) 
exit( 1 ); /* Fail for OS/2 or monochrome */ 
oldapage = _getactivepage(); 
oldvpage = _getvisualpage(); 
_displaycursor( _GCURSOROFF ); 


/* Draw arrows in different place on each page. */ 
for( page = 1; page < 4; paget+t+ ) 
{ 
_setactivepage( page ); 
_settextposition( 12, 16 * page ); 
_outtext( "d>>>>>>>>"_ ); 
} 


while( !kbhit() ) 
/* Cycle through pages 1 to 3 to show moving image. */ 
for( page = 1; page < 4; page++ ) 
_setvisualpage( page ); 
getch(); 


/* Restore original page (normally @) to restore screen. */ 
_setactivepage( oldapage ); 

_setvisualpage( oldvpage ); 

_displaycursor( _GCURSORON ); 
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_Setbkcolor 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Sets the current background color. 


#include <graph.h> 


‘long far _setbkcolor( long color ); 


color Desired color 


The _setbkcolor function sets the current background color to the color value color. 


In a color text mode (such as_TEXTC80), setbkcolor accepts (and _getbkcolor returns) 
a color index. The value for the default colors is given in a table in the description of the 
_settextcolor function. For example, _setbkcolor(2L) sets the background color to color 
index 2. The actual color displayed depends on the palette mapping for color index 2. The 
default is green in a color text mode. 


In a color graphics mode (such as ERESCOLOR), setbkcolor accepts (and _getbkcolor 
returns) a color value. The value for the background color is given by the manifest con- 
stants defined in the GRAPH.H include file. For example, _setbkcolor(_GREEN) sets the 
background color in a graphics mode to green. These manifest constants are provided as a 
convenience in defining and manipulating the most common colors. The actual range of 


colors is, in general, much greater. 


In general, whenever an argument is long, it refers to a color value, and whenever it is 
short, it refers to a color index. The two exceptions are _setbkcolor and _getbkcolor. 


Since the background color is color index 0, the _remappalette function will act identi- 
cally to the _setbkcolor function. Unlike _Pemappatente, however, _setbkcolor does not 
require an EGA or VGA environment. 


In a text mode, the _setbkcolor function does not affect anything already appearing on the 
display; only the subsequent output is affected. In a graphics mode, it immediately changes 
all background pixels. 


In text modes, _setbkcolor returns the color index of the old background color. In graphics 
modes, _setbkcolor returns the old color value of color index 0. There is no error return. 


O ANS! @ DOS WM oOS/2 O UNIX OO XENIX 
_getbkcolor, _remappalette, _selectpalette 


See the example for _getcolor. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Controls stream buffering. 
#include <stdio.h> 
void setbuf( FILE *stream, char *buffer ); 


stream Pointer to FILE structure 


buffer User-allocated buffer 


The setbuf function allows the user to control buffering for stream. The stream argument 
must refer to an open file that has not been read or written. If the buffer argument is NULL, 
the stream is unbuffered. If not, the buffer must point to a character array of length 
BUFSIZ, where BUFSIZ is the buffer size as defined in STDIO.H. The user-specified buff- 
er, instead of the default system-allocated buffer for the given stream, is used for I/O 
buffering. 


The stderr and (in DOS only) stdaux streams are unbuffered by default, but may be as- 
signed buffers with setbuf. 


The setbuf function has been subsumed by the setvbuf function, which should be the pre- 
ferred routine for new code. The setbuf function is retained for compatibility with ex- 
isting code. 


None. 
@ ANS! @ DOS @oSs/2 MW UNIX’ QB XENIX 


fclose, fflush, fopen, setvbuf 


/* SETBUF.C: This program first opens files named DATA1 and DATA2. 
* Then it uses setbuf to give DATA] a user-assigned buffer 
* and to change DATA2 so that it has no buffer. 


a 


#Hinclude <stdio.h> 


void main() 


{ 


char buf(BUFSIZ]); 
FILE *streaml, *stream2; 
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if( ((streaml 
((stream2 


fopen( “datal", "a" )) != NULL) && 
fopen( "data2", “w" )) != NULL) ) 


( 
/* "streaml" uses user-assigned buffer: */ 
setbuf( streaml, buf ); 
printf( “streaml set to user-defined buffer at: %Fp\n", buf ); 


/* “stream2" is unbuffered */ 
setbuf( stream2, NULL ); 

printf( “stream2 buffering disabled\n" ); 
fcloseall(); 


Output 


streaml set to user-defined buffer at: 0298:Q0DF2 
stream2 buffering disabled 
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Description Sets the clipping region for graphics. 
#include <graph.h> 


void far _setcliprgn( short x/, short y/, short x2, short y2 ); 


xl, yl Upper-left corner of clip region 
x2, y2 Lower-right comer of clip region 
Remarks The _setcliprgn function limits the display of subsequent graphics output and font text out- 


put to an area of the screen called the “clipping region.” The physical points (x/, y/) and 
(x2, y2) are the diagonally opposed sides of a rectangle that defines the clipping region. 
This function does not change the view coordinate system. Rather, it merely masks the 
screen. 


Note that the _setcliprgn function affects graphics and font text output only. To mask the 
screen for text output, use the _settextwindow function. 


Return Value None. 

Compatibility O ANS! @ DOS OF O0S7?2 O UNIX O XENIX 

See Also _settextwindow, _setvieworg, _setviewport, _setwindow 
Example 


/* SCLIPRGN.C */ 

#Hinclude <stdlib.h> 
#include <conio.h> 
#Hinclude <graph.h> 


void main() 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


/* Set clip region, then draw and ellipse larger than the region. */ 
_setcliprgn( @, @, 200, 125 ); 
—ellipse( _GFILLINTERIOR, 88, 50, 240, 198 ); 
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getch(); 
_setvideomode( _DEFAULTMODE ); 
} 
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SS SSS SE SL 
Description . Sets the current color. 

#include <graph.h> 

short far _setcolor( short color ); 

color Desired color index 


Remarks The _setcolor function sets the current color index to color. The color parameter is 
masked but always within range. The following graphics functions use the current color: 
_arc, ellipse, floodfill, lineto, outgtext, pie, rectangle, and _setpixel. 


The _setcolor function accepts an int value as an argument. It is a color index. 
The default color index is the highest numbered color index in the current palette. 


Note that the _setcolor function does not affect the output of the presentation-graphics 
functions. 


Return Value This function returns the previous color. If the function fails (e.g., if used in a text mode), 
it returns —1.' 


Compatibility O ANS| @ DOS QO OS/f ODO UNIX OO XENIX 


See Also _arc functions, _ellipse functions, _floodfill, _getcolor, _lineto functions, _outgtext, 
_pie functions, _rectangle functions, _selectpalette, _setpixel functions 


Example 


/* GPIXEL.C: This program assigns different colors to randomly 
* selected pixels. 
x7 


#Finclude <conio.h> 
#Finclude <stdlib.h> 
#Hinclude <graph.h> 
void main() 


short xvar, yvar; 
struct videoconfig vc; 
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/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXCOLORMODE ) ) 

exit( 1 ); . 
_getvideoconfig( &vc ); 


/* Draw filled ellipse to turn on certain pixels. */ 
_ellipse( _GFILLINTERIOR, vce.numxpixels / 6, vc.numypixels / 6, 
ve.numxpixels / 6 * 5, vc.numypixels / 6 * 5 ); 


/* Draw random pixels in random colors... */ 
while( !kbhit() ) 
{ 
/* ...but only if they are already on (inside the ellipse). */ 
xvar = rand() % vc.numxpixels; 
yvar = rand() % ve.numypixels; 
if( _getpixel( xvar, yvar ) !=@ ) 
{ 


I 


_setcolor( rand() % 16 ); 
_setpixel( xvar, yvar ); 
} 
} 


getch(); /* Throw away the keystroke. */ 
_setvideomode( _DEFAULTMODE.); 
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Description _ Sets the fill mask. 


#include <graph.h> 
void far _setfillmask( unsigned char _far *mask ); 
mask Mask array 


Remarks The _setfillmask function sets the current fill mask, which determines the fill pattern. The 
mask is an 8-by-8 array of bits in which each bit represents a pixel. A 1 bit sets the corre- 
sponding pixel to the current color, while a 0 bit leaves the pixel unchanged. The pattern is 
repeated over the entire fill area. 


If no fill mask is set (mask is NULL—the default), only the current color is used in fill 
operations. 


Return Value None. 
Compatibility O ANS| @ DOS OF OS/2 O UNIX OO XENIX 
See Also _ellipse functions, _floodfill, _getfillmask, _pie functions, _rectangle functions 


Example 
/* GFILLMSK.C: This program illustrates _getfilimask and _setfillmask. */ 
dtinclude <conio.h> 


#Hinclude <stdlib.h> 
#Hinclude <graph.h> 


void ellipsemask( short xl, short yl, short x2, short y2, char _far *newmask ); 


{ 0x43, 0x23, Ox7c, Oxt7, Ox8a, Ox4d, Ox78, 0x39 }; 
{ @x18, Oxad, O@xcO, 9x79, Oxf6, Oxc4, Oxa8B, Bx23 }; 


unsigned char mask1{8] 
unsigned char mask2{[8] 
char oldmask([8]; - 


void main() 
{ 
int loop; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 
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} 


/* Set first fill mask and draw rectangle. */ 
_setfillmask( maskl ); 

_rectangle( _GFILLINTERIOR, 20, 20, 100, 100 
getch(); 


/* Call routine that saves and restores mask. 
ellipsemask( 68, 60, 158, 158, mask2 ); 
getch(); 


/* Back to original mask. */ 


3 


ud 


_rectangle( _GFILLINTERIOR, 120, 120, 190, 190 ); 


getch(); 


_setvideomode( _DEFAULTMODE ); 


/* Draw an ellipse with a specified fill mask. */ 
void ellipsemask( short xl, short yl, short x2, short y2, char _far *newmask ) 


{ 


unsigned char savemask({8]; 


_getfillmask( savemask ); 
_setfillmask( newmask ); 
—~ellipse( _GFILLINTERIOR, xl, yl, x2, y2 ); 
_setfillmask( savemask ); 


/* 
/* 
/* 
/* 


Save mask 

Set new mask 
Use new mask 
Restore original 


*7 
ah 
x) 
*} 
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Description Finds a single font. 

#include <graph.h> 

short far _setfont( unsigned char far *options ); 

options String describing font characteristics 


Remarks The _setfont function finds a single font, from the set of registered fonts, that has the char- 
acteristics specified by the options string. If a font is found, it is made the current font. The 
current font is used in all subsequent calls to the _outgtext function. There can be only one 
active font at any time. 


The options string is a set of characters that specifies the desired characteristics of the font. 
The _setfont function searches the list of registered fonts for a font matching the specified 
characteristics. 


The characteristics that may be specified in the options string are shown in the list below. 
Characteristics specified in the options string are not case- or position-sensitive. 


Characteristic Description 

t’fontname’ Typeface. 

hx Character height, where x is the number of pixels. 

wy Character width, where y is the number of pixels. 

f Find only a fixed-space font (should not be used with the 

p characteristic). 

p Find only a proportionally spaced font (should not be used 
with the f characteristic). 

Vv Find only a vector font (should not be used with the r 
characteristic). 

r Find only a raster-mapped (bit-mapped) font (should not be 
used with the v characteristic). 

b . Select a best fit font. 

nx Select font number x, where x is less than or equal to the value 


returned by the _registerfonts function. Use this option to 
“step through” an entire set of fonts. 
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You can request as many options as desired, except with nx, which should be used alone. 
If mutually exclusive options are requested (such as the pair f/p or r/v), the _setfont func- 
tion ignores them. There is no error detection for incompatible parameters used with nx. 


Options can be separated by blanks in the options string. Any other character is ignored by 
setfont. 


The t (the typeface specification) in options is specified as a “t’” followed by fontname in 
single quotes. Choose fontname from the following list: 


Fontname Description 
Courier Fixed-width bit-mapped font with serifs 
Helv Sans serif proportional bit-mapped font 
_Tms Rmn Proportional bit-mapped font with serifs 
Script Proportional vector-mapped font of slanted characters formed 
from nearly continuous lines 
Modern Proportional vector-mapped font without serifs 
Roman Proportional vector-mapped font with serifs 


A b in the options field causes the _setfont routine to automatically select the “best fit” 
font that matches the other characteristics you have specified. If the b parameter is spec- 
ified and at least one font is registered, _setfont will always be able to set a font and will 
return 0 to indicate success. 


In selecting a font, the _setfont routine uses the following precedence (rated from highest 
precedence to lowest): 
_ L. Pixel height 
2. Typeface 
3. Pixel width 


4, Fixed or proportional font 


You can also specify a pixel width and height for fonts. If a nonexistent value is chosen for 
either, and the b option is specified, the _setfont function will chose the closest match. A 
smaller font size has precedence over a larger size. If _setfont requests Helv 12 with best 

_ fit, and only Helv 10 and Helv 14 are available, setfont will select Helv 10, 


If a nonexistent value is chosen for pixel height and width, the _setfont function will apply 
a magnification factor to a vector-mapped font to obtain a suitable font size. This auto- 
matic magnification does not apply if the r (raster-mapped font) option is specified, or if a 
specific typeface is requested and no best fit (b) option is specified. 
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If you specify the nx parameter, _setfont will ignore any other specified options and 
supply only the font number corresponding to x. 


Note that the font functions affect only the output from the font output function _outgtext; 
no other C run-time output functions are affected by font usage. 


Return Value The _setfont function returns a 0 to indicate success and a —1 to indicate an error. An 
error occurs if a request for a specific font fails and the b option was not specified, or if 
fonts have not yet been registered. 


Compatibility O ANS! @ DOS O os7 QO UNIX O XENIX 
See Also _getfontinfo, getgtextextent, outgtext, registerfonts, _unregisterfonts 


Example See the example for _outgtext. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Changes the orientation of font text output. 

#include <graph.h> 

struct xycoord far _setgtextvector( short x, short y ); 

x,y Integers specifying font rotation 

The _setgtextvector function sets the current orientation for font text output to the vector 


specified by x and y. The current orientation is used in calls to the _outgtext function. 


The values of x and y define the vector which determines the direction of rotation of font 
text on the screen. The text-rotation options are shown below: 


(x, y) Text Orientation 

(0, 0) Unchanged 

(1,0) Horizontal text (default) 

(0, 1) Rotated 90 degrees counterclockwise 
(—1, 0) Rotated 180 degrees 

(0, -1) Rotated 270 degrees counterclockwise 


If other values are input, only the sign of the input is used. For example, (—3, 0) is inter- _ 
preted as (-1, 0). 


The _setgtextvector function returns the previous vector in a structure of xycoord type. If 
you pass the _setgtextvector function the values (0, 0), the function returns the current 
vector values in the xycoord structure. 
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_getfontinfo, _getgtextextent, grstatus, outgtext, registerfonts, _setfont, 
_unregisterfonts 


See the example for _outgtext. 


setjmp 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Saves the current state of the program. 

#include <setjmp.h> 

int setjmp( jmp_buf env ); 

env Variable in which environment is stored 


The setjmp function saves a stack environment that can be subsequently restored using 
longjmp. Used together this way, setjmp and longjmp provide a way to execute a “non- 
local goto.” They are typically used to pass execution control to error-handling or recovery 
code in a previously called routine without using the normal calling or return conventions. 


A call to setjmp causes the current stack environment to be saved in env. A subsequent 
call to longjmp restores the saved environment and returns control to the point just after 
the corresponding setjmp call. All variables (except register variables) accessible to the 
routine receiving control contain the values they had when setjmp was called. 


The setjmp function returns 0 after saving the stack environment. If setjmp returns as a re- 
sult of alongjmp call, it returns the value argument of longjmp, or, if the value argument 
of longjmp is 0, setjmp returns 1. There is no error return. 
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longjmp 


See the example for _fpreset. 
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_Setlinestyle 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Sets the line style. 

#include <graph.h> 

void far _setlinestyle( unsigned short mask ); 

mask Desired line-style mask 

Some graphics routines (_lineto and _rectangle) draw straight lines on the screen. The 


type of line is controlled by the current line-style mask. 


The _setlinestyle function selects the mask used for line drawing. The mask argument is a 
16-bit array, where each bit represents a pixel in the line being drawn. If a bit is 1, the 


- corresponding pixel is set to the color of the line (the current color). If a bit is 0, the corre- 


sponding pixel is left unchanged. The template is repeated for the entire length of the line. 


The default mask is OxXFFFF (a solid line). 

None. 

O ANS! @ DOS OF OS/72 O UNIX O XENIX- 
_getlinestyle, _lineto functions, rectangle functions 


See the example for _getlinestyle. 
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Description Defines the locale. 
#include <locale.h> 


char *setlocale( int category, const char */ocale ); 


category Category affected by locale 
locale Name of the locale that will control the specified category 
Remarks The setlocale function sets the categories specified by category to the locale specified by 


locale. The “locale” refers to the locality (country) for which certain aspects of your pro- 
gram can be customized. Some locale-dependent aspects include the formatting of dates 
and the display format for monetary values. 


The setlocale function is used to set or get the program’s current entire locale or simply 
portions of the locale information. The category argument specifies which portion of a pro- 
gram’s locale information will be used. The manifest constants used for the category argu- 


ment are listed below: 

Category Parts of Program Affected 

LC_ALL All categories listed below. 

LC_COLLATE The strcoll and strxfrm functions. 

LC_CTYPE The character-handling functions (except for isdigit and 
isxdigit, which are unaffected). 

LC_MONETARY Monetary formatting information returned by the localeconv 
function. 

LC_NUMERIC Decimal point character for the formatted output routines 
(such as printf), for the data conversion routines, and for 
the nonmonetary formatting information retumed by the © 
localeconv function. 

LC_TIME The strftime function. 


The locale argument is a pointer to a string that specifies the name of the locale. If 
locale points to an empty string, the locale is the implementation-defined native environ- 
ment. A value of “C” specifies the minimal ANSI conforming environment for C transla- 
tion. This is the only locale supported in Microsoft C, version 6.0. 


If the locale argument is a null pointer, setlocale returns a pointer to the string associated 
with the category of the program’s locale. The program’s current locale setting is not 
changed. 
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Return Value If a valid locale and category are given, _setlocale returns a pointer to the string associated 
with the specified category for the new locale. If the locale or category is invalid, the 
setlocale function returns a null pointer and the program’s current locale settings are not 
changed. 


The pointer to a string returned by setlocale can be used in subsequent calls to restore that 
part of the program’s locale information. Later calls to setlocale will overwrite the string. 
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See Also localeconvy, strcoll, strftime, strxfrm 
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Description Sets the file translation mode. 
#include <fcntl.h> 
#include <io.h> Required only for function declarations 


int setmode ( int handle, int mode ); 


handle File handle 
mode New translation mode 
Remarks The setmode function sets to mode the translation mode of the file given by handle. The 


mode must be one of the following manifest constants: 


Constant Meaning 


O_TEXT Sets text (translated) mode. Carriage-return—line-feed (CR- 
LF) combinations are translated into a single line-feed (LF) 
character on input. Line-feed characters are translated into CR- 
LF combinations on output. 


O_BINARY Sets binary (untranslated) mode. The above translations are 
suppressed. 


The setmode function is typically used to modify the default translation mode of stdin, 
stdout, stderr, stdaux, and stdprn, but can be used on any file. If setmode is applied to 
the file handle for a stream, the setmode function should be called before any input or out- 
put operations are performed on the stream. 


Return Value If successful, setmode returns the previous translation mode. A return value of —1 indi- 
cates an error, and errno is set to one of the following values: 


Value Meaning 
EBADF Invalid file handle 
EINVAL Invalid mode argument (neither O_TEXT nor O_BINARY ) 
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See Also creat, fopen, open 


Example 


/* SETMODE.C: This program uses setmode to change stdin from text 
* mode to binary mode. 
* / 


dHinclude <stdio.h> 
dHinclude <fcentl.h> 
#Hinclude <io.h> 


void main() 
{ 
int result; 


/* Set “stdin" to have binary mode: */ 
result = setmode( fileno( stdin ), O_BINARY ); 
if( result == -1 ) 
perror( "Cannot set mode" ); 
else 
printf( "“'stdin' successfully changed to binary mode\n" ); 


Output 


‘stdin' successfully changed to binary mode 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Set a pixel to the current color. 
#include <graph.h> 


short far _setpixel( short x, short y ); 


short _far _setpixel_w( double wx, double wy ); 


x,y . Target pixel 

wx, wy Target pixel 

The _setpixel and the _setpixel_w functions set a pixel at a specified location to the 
current color. 

The _setpixel function sets the pixel at the view-coordinate point (x, y) to the current color. 


The _setpixel_w function sets the pixel at the window-coordinate point (wx, wy) to the 
current color. 


The function returns the previous value of the target pixel. If the function fails (for ex- 
ample, the point lies outside of the clipping region), it will return ~1. 


O ANS! @ DOS OF OS/2 O UNIX O XENIX 


_getpixel functions, _setcolor 


/* GPIXEL.C: This program assigns different colors to randomly 
* selected pixels. 


ui 


#iinclude <conio.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 


void-main() 


{ 


short xvar, yvar; 
struct videoconfig vc; 
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/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1); 

_getvideoconfig( &vc ); 


/* Draw filled ellipse to turn on certain pixels. */ 
_ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6, 
ve.numxpixels / 6 * 5, vc.numypixels / 6 * 5 ); 


/* Draw random pixels in random colors... */ 
while( !tkbhit() ) 
{ 
/* ...but only if they are already on (inside the ellipse). */ 
xvar = rand() % vc.numxpixels; 
yvar = rand() % vc.numypixels; 
if( _getpixel( xvar, yvar ) !=@ ) 
{ 


_setcolor( rand() % 16 ); 
_setpixel( xvar, yvar ); 
} 
} 


getch(); /* Throw away the keystroke. */ 
_setvideomode( _DEFAULTMODE ); 


_Settextcolor : 668 


Description 


Remarks 


Return Value 


Sets the current text color. 

#include <graph.h> 

short far _settextcolor( short index ); 

index Desired color index 


The _settextcolor function sets the current text color to the color index specified by index. 
The default text color is the same as the maximum color index. 


The _settextcolor routine sets the color for the _outtext and _outmem functions only. It 
does not affect the color of the printf function or the color of text output with the 
_outgtext font routine. Use the _setcolor function to change the color of font output. 


In text color mode, you can specify a color index in the range 0-31. The colors in the 
range 0-15 are interpreted as normal (non-blinking). The normal color range is defined 
below: 


Index Color Index Color 

0 Black 8 Dark gray 

1 . Blue 9 Light blue 

2 Green 10 Light green 

3 Cyan 11 Light cyan 

4 Red 12 Light red 

) Magenta 13 Light magenta 
6 Brown 14 Yellow 

7 White 15 Bright white 


Blinking is selected by adding 16 to the normal color value. 


In every text mode, including monochrome, _getvideoconfig returns the value 32 for the 
number of available colors. The value 32 indicates the range of values (0-31) accepted by 
the _settextcolor function. This includes sixteen normal colors (0-15) and sixteen blink- 
ing colors (16-31). Monochrome text mode has fewer unique display attributes, so some 
color values are redundant. However, because blinking is selected in the same manner, 
monochrome text mode has the same range (0-31) as other text modes. 


. The function returns the color index of the previous text color. There is no error return. 
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See Also _gettextcolor, _outtext 
Example 

/* QUTTXT.C: This example illustrates text output functions: 

* _gettextcolor _getbkcolor -_gettextposition _outtext 
* _settextcolor _setbkcolor _settextposition 

*/ 


#Finclude <conio.h> 
dfinclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [80]; 


void main() 


{ 


/* Save original foreground, background, and text position */ 
short biink, fad, oldfgd; 

long bgd, oldbgd; 

struct rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 
oldbgd = _getbkcolor(); 
oldpos = _gettextposition(); 
_Clearscreen( _GCLEARSCREEN ); 
/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 
{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bgd < 8; bgd++ ) 
{ 
_setbkcolor( bad ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 


_Settextcolor " 670 


/* Loop through 16 foreground colors. */ 
for( fod = @; fgd < 16; fgdt+ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_Clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 
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_ Setiextcursor 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Sets the current cursor attribute. 

#include <graph.h> 

short far _settextcursor( short attr ); 

attr Cursor attribute 


The _settextcursor function sets the cursor attribute (i.e., the shape) to the value specified 
by attr. The high-order byte of attr determines the top line of the cursor within the charac- 
ter cell. The low-order byte of attr determines the bottom line of the cursor. 


The _settextcursor function uses the same format as the BIOS routines in setting the cur- 
sor. Typical values for the cursor attribute are listed below: 


Attribute Cursor Shape 
0x0707 Underline 
0x0007 Full block cursor 
0x0607 | Double underline 
0x2000 No cursor 


Note that this function works only in text video modes. 


The function returns the previous cursor attribute, or —1 if an error occurs (such as calling 
the function in a graphics screen mode). 
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_displaycursor, _gettextcursor 


/* DISCURS.C: This program changes the cursor shape using _gettextcursor 


ss 


* and _settextcursor, and hides the cursor using _displaycursor. 


#Hinclude <conio.h> 
#Hinclude <graph.h> 
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void main() 
{ 
short oldcursor; 
short newcursor = Ox@Q7; © /* Full block cursor */ 


/* Save old cursor shape and make sure cursor is on. */ 
oldcursor = _gettextcursor(); 

_Clearscreen( _GCLEARSCREEN ); 

_displaycursor( _GCURSORON ); 

—outtext( "\nOld cursor shape: " ); 

getch(); 


/* Change cursor shape. */ 
_Outtext( "\nNew cursor shape: " ); 
—_settextcursor( newcursor ); 
getch(); 


/* Restore original cursor shape. */ 
_outtext( "\n" ); 
_settextcursor( oldcursor ); 
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_settextposition 


Description 


Remarks 


Return Value 


Sets the text position. 

#include <graph.h> 

struct recoord far _settextposition( short row, short column ); 
row, column New output start position 


The _settextposition function sets the current text position to the display point 
(row, column). The _outtext and _outmem functions (and standard console I/O routines, 
such as printf) output text at that point. 


The rcecoord structure, defined in GRAPH.H, contains the following elements: 


Element Description 
short row Row coordinate 
short col Column coordinate 


The function returns the previous text position in an recoord structure, defined in 
GRAPH.H. 


Compatibility O ANS! m@ DOS mm oOS/72 O UNIX OC XENIX 
See Also _gettextposition, outtext, _settextwindow 

Example 

/* QUTTXT.C: This example illustrates text output functions: 

* _gettextcolor _getbkcolor -_gettextposition _outtext 
< _settextcolor ._setbkcolor -_settextposition 

*/ 


fHinclude <conio.h> 
fHinclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [80]; 


void main() 


{ 


_Settexiposition 
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} 


/* Save original foreground, background, and text position */ 
short blink, fad, oldfgd; 
long bgd, oldbgd; 

struct rccoord: oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

Oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 


/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 
{ 
/* Loop through 8 background colors. */ 
for( bod = 0; bgd < 8; bgd++ ) 
{ 
_setbkcolor( bad ); 
_settextposition( (short)bgd + ((blink / 16) * 9) +3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bad ); 
_outtext( buffer ); 


/* Loop through 16 foreground colors. */ 
for( fgd = @; fgd < 16; fgd++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 


} 
} 
getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 


‘ 
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Description Sets the number of screen rows for text modes. 

#include <graph.h> 

short far _settextrows( short rows ); 

rows Number of text rows 
Remarks The _settextrows function specifies the number of screen rows to be used in text modes. 


Return Value 
Compatibility 
See Also 


Example 


If the constant_MAXTEXTROWS is specified for the rows argument, the function 
will choose the maximum number of rows available. In text modes, this is 50 rows on 
VGA, 43 on EGA, and 25 on others. In graphics modes that support 30 or 60 rows, 
_MAXTEXTROWS specifies 60 rows. . 


This function returns the numbers of rows set. The function returns O if an error occurred. 
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_getvideoconfig, _setvideomode, _setvideomoderows 


/* STXTROWS.C: This program attempts to set the screen height. It returns 
* an errorlevel code of 1 (fail) or @ (success) that could be tested in 


* a batch file. 


ef 


dHinclude <graph.h> 
#Hinclude <stdlib.h> 


void main( int argc, char **argv ) 


{ 


short rows; 


if( !Crows 


{ 


atoi( argv[l] )) ) 


—outtext( "\nSyntax: STXTROWS [ 25 | 43 | 58 J\n" ); 
exit( 1 ); 


} 
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/* Make sure new rows are the same as requested rows. */ 
if( _settextrows( rows ) != rows ) 
{ 
_outtext( "\nInvalid rows\n" ); 
exit( 1 ); 
J 
else 
exit( @ ); 
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Description Creates a text window. 

#include <graph.h> 

void far _settextwindow( short r/, short c/, short r2, short c2 ); | 

rl,cl Upper-left corner of cindow 

r2,c2 Lower-right comer of window 
Remarks The _settextwindow function specifies a window in row and column coordinates where 


Return Value 
Compatibility 
See Also 


Example 


all text output to the screen is displayed. The arguments (r/, cl) specify the upper-left 
comer of the text window, and the arguments (r2, c2) specify the lower-right corner of the 
text window. 


Text is output from the top of the text window down. When the text window is full, the 
uppermost line scrolls up out of it. 


Note that this function does not affect the output of presentation-graphics text (e.g., labels, 
axis marks, etc.). It also does not affect the output of the font display routine _outgtext. 
Use the _setviewport function to control the display area for presentation graphics or 
fonts. 


None. 
O ANS! @ DOS mOS2 O UNIX OC XENIX 
_gettextposition, _gettextwindow, _outtext, _settextposition 


See the example for _scrolltextwindow. 
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Description Controls stream buffering and buffer size. 
#include <stdio.h> 


int setvbuf( FILE “stream, char *buffer, int mode, size_t size ); 


stream Pointer to FILE structure 
buffer —  User-allocated buffer 
mode Mode of buffering: _IOFBF (full buffering), IOLBF (line 
buffering), IONBF (no buffer) 
size Size of buffer 
Remarks The setvbuf function allows the program to control both buffering and buffer size for 


stream. The stream must refer to an open file that has not been read from or written to 
since it was opened. The array pointed to by buffer is used as the buffer, unless it is NULL, 
and an automatically allocated buffer size bytes long is used. 


The mode must be _IOFBF, IOLBF, or _IONBF. If mode is _IOFBF or _IOLBF, then size 
is used as the size of the buffer. If mode is IONBF, the stream is unbuffered and size and 
buffer are ignored. 


Values for mode and their meanings are: 


Type Meaning 


_IOFBF Full buffering; that is, buffer is used as the buffer and size is 
used as the size of the buffer. If buffer is NULL, an automat- 
ically allocated buffer size bytes long is used. 


_IOLBF Under DOS and OS/2, the same as IOFBF. 
_IONBF No buffer is used, regardless of buffer or size. 


The legal values for size are greater than 0 and less than 32,768. 


Return Value The return value for setvbuf is 0 if successful, and a nonzero value if an illegal type or 
buffer size is specified. 
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Compatibility BM ANS| @ DOS #8 OS/2 @ UNIX 0 XENIX 
See Also — fclose, fflush, fopen, setbuf 
Example 


/* SETVBUF.C: This program opens two streams named streaml and stream2. 
* It then uses setvbuf to give streaml a user-defined buffer of 1824 
* bytes and stream2 no buffer. 

*/ 


fHinclude <stdio.h> 


void main() 
( 
char buf[1024]; 
FILE *streaml, *stream2; 


if( ((streaml 
((stream2 


fopen( “datal", "a" )) != NULL) && 
fopen( “data2", "w" )) != NULL) ) 


i oil 


{ 
if( setvbuf( streaml, buf, _IOFBF, sizeof( buf ) ) !=@ ) 
printf( “Incorrect type or size of buffer for streaml\n" ); 
else 
printf( "'streaml' now has a buffer of 1824 bytes\n" ); 
if( setvbuf( stream2, NULL, _IONBF, 8 ) !=@ ) 
printf( “Incorrect type or size of buffer for stream2\n" ); 
else 
printf( ""stream2' now has no buffer\n" ); 
fcloseall(); 


Output 


"streaml’ now has a buffer of 1824 bytes 
"stream2' now has no buffer 
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Description 


Remarks 


Sets the video mode. 
#include <graph.h> 
short _far _setvideomode( short mode ); 
mode Desired mode 


The _setvideomode function selects a screen mode appropriate for a particular hard- 
ware/display configuration. The mode argument can be one of the manifest constants 
shown in Table R.9 and defined in GRAPH.H. 


Table R.9 Manifest Constants for Screen Mode 


Mode Type! Size” Colors? Adapter’ 
_DEFAULTMODE Hardware default 

mode 
_MAXRESMODE Highest resolution 

‘in graphics mode 
_MAXCOLORMODE Maximum colors 

in graphics mode 
_TEXTBW40 M/T 40 x 25 16 CGA 
_TEXTC40 C/T 40 x 25 16 CGA 
_TEXTBWS80 M/T 80 x 25 16 CGA 
_TEXTC80 C/T 80 x 25 6 CGA 
_MRES4COLOR C/G 320 x 200 4 CGA 
_MRESNOCOLOR M/G 320 x 200 4 CGA 
_HRESBW M/G 640 x 200 Z CGA 
_TEXTMONO M/T 80 x 25 1 MDPA 
_HERCMONO® Hercules graphics 720 x 348 HGC 
_MRES16COLOR C/G 320 x 200 16 EGA 
_HRESI6COLOR C/G 640 x 200 16 EGA 
_ERESNOCOLOR M/T 640 x 350 l EGA 


_ERESCOLOR C/G 640 x 350 16 EGA 
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Table R.9 = (continued) . 
1 Pane 4 3 4 
Mode Type Size Colors Adapter 
_VRES2COLOR C/G 640x480 2 VGA 
_VRES16COLOR C/G 640 x 480 16 VGA 
_MRES256COLOR C/G 320 x 200 256 VGA 
_ORESCOLOR C/G 640 x 400 1 of 16 OLIV 
1. M indicates monochrome, C indicates color output, T indicates text, and G indicates graphics generation. 
2. For text modes, size is given in characters (columns x rows). For graphics modes, size is given in pixels 
(horizontal x vertical). 
3. For monochrome displays, the number of colors is the number of gray shades. 
4. Adapters are the IBM (and compatible) Monochrome Adapter (MDPA), Color Graphics Adapter (CGA), 
Enhanced Graphics Adapter (EGA), Video Graphics Array (VGA), Hercules-compatible adapter (HGC), and 
Olivetti-compatible adapter (OLIV). 
5. In_LHERCMONO mode, the text dimensions are 80 columns by 25 rows, with a 9 by 14 character box. The 
bottom two scan lines of row 25 are not visible. 
Note that only standard hardware is described here, but display hardware that is strictly 
compatible with IBM, Hercules, or Olivetti hardware should also work as described. 
_MAXRESMODE and The two special modes __MAXRESMODE and MAXCOLORMODE select the highest reso- 
_MAXCOLORMODE 


lution or greatest number of colors available with the current hardware, respectively. 
These two modes fail for adapters that do not support graphics modes. 


Table R.10 lists the video mode selected for different adapter and monitor combinations 
when _MAXRESMODE or MAXCOLORMODE is specified: 


Table R.10 Modes Selected by MAXRESMODE and MAXCOLORMODE 


Adapter/Monitor _MAXRESMODE _MAXCOLORMODE 
MDPA fails fails 

HGC _HERCMONO . _HERCMONO 

CGA color* _HRESBW _MRES4COLOR 

CGA noncolor* _HRESBW _MRESNOCOLOR 
OCGA _ORESCOLOR _MRES4COLOR 

OEGA color _ORESCOLOR _ERESCOLOR 

EGA color 256K _HRES16COLOR _HRES1I6COLOR 


EGA color 64K _HRES16COLOR _HRES16COLOR 
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Hercules Support 


Return Value 


Compatibility 


See Also 


Example 


Table R.10 (continued) 


Adapter/Monitor _MAXRESMODE _MAXCOLORMODE 
EGA ecd 256K _ERESCOLOR _ERESCOLOR 

EGA ecd 64K _ERESCOLOR _HRESI6COLOR 

EGA mono _ERESNOCOLOR . _ERESNOCOLOR 
MCGA _VRES2COLOR _MRES256COLOR 
VGA _VRESI6COLOR _MRES256COLOR 
OVGA _VRES16COLOR _MRES256COLOR 


* Color monitor is assumed if the start-up text mode was TEXTC80 or TEXTC40 or if the start-up mode 
was graphics mode. Composite or other noncolor CGA monitor is assumed if start-up mode was TEXTBW80 or 
TEXTBW40. 


You must install the Hercules driver MSHERC.COM before running your program. Type 
MSHERC to load the driver. This can be done from an AUTOEXEC.BAT file. 


If you have both a Hercules monochrome card and a color video card, you should install 
MSHERC.COM with the /H (/HALF) option. The /H option causes the driver to use one 
instead of two graphics pages. This prevents the two video cards from attempting to use 
the same memory. You do not have to use the /H option if you have only a Hercules card. 
See your Hercules hardware manuals for more details of compatibility. 


To use a mouse, you must follow special instructions for Hercules cards in Microsoft 
Mouse Programmer’ s Reference Guide. (This is sold separately; it is not supplied with 
either Microsoft C or the mouse package.) 


The function returns the number of text rows if the function is successful. If an error is en- 
countered (that is, the mode selected is not supported by the current hardware configura- 
tion), the function returns O. 


O ANS! @ DOS # OS/2 O UNIX O XENIX 


In OS/2, only text video modes may be selected by _setvideomode. 


_getvideoconfig, _settextrows, _setvideomoderows 


/* SVIDMODE.C: This program sets a video mode from a string given on the 
* command line. 


*/ 
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#include <graph.h> 
#tinclude <stdlib.h> 
#tinclude <string.h> 


short modes{J = { _TEXTBW4@, _TEXTC4@, _TEXTBW88, 
_TEXTC8@, _MRES4COLOR, _MRESNOCOLOR, 
_HRESBW, _TEXTMONO, _HERCMONO, 
_MRESI6COLOR, _HRESI6COLOR, _ERESNOCOLOR, 
_ERESCOLOR, _VRES2COLOR, _VRESI6COLOR, 
_MRES256COLOR, _ORESCOLOR 

i 

char *names[] = ( “TEXTBW40", "TEXTC48", "TEXTBW80", 
"TEXTC8O", "MRES4COLOR", “MRESNOCOLOR", 
"HRESBW", "TEXTMONO", "HERCMONO", 
"MRESI6COLOR", “HRESI6COLOR", "ERESNOCOLOR", 
"ERESCOLOR", "VRES2COLOR", "VRESI6COLOR", 


"MRES256COLOR" , “ORESCOLOR” 
}; 


void error( char *msg ); 


void main( int argc, char *argv({] ) 

{ 
short i, num = sizeof( modes ) / sizeof( short ); 
struct videoconfig vc; 


if( arge < 2 ) 
error( "No argument given" ); 


/* If matching name found, change to corresponding mode. */ 
for( i = @; i < num; i++ ) 
{ 
if( !strcempi( argv(1], namesCi] ) ) 
{ 
_setvideomode( modes{i] ); 
_outtext( “New mode is: " ); 
_outtext( names[i] ); 
exit( 0 ); 
} 
} 
error( “Invalid mode string" ); 
} 


void error( char *msg ) 
{ 
_outtext( msg ); 
exit( 1 ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


"7 * SVMROWS.C */ 


Sets the video mode and number of text rows for text modes. 
#include <graph.h> 
short far _setvideomoderows( short mode, short rows ); 


mode Desired mode 


rows Number of text rows 


The _setvideomoderows function selects a screen mode for a particular hardware/display 
combination. The manifest constants for the screen mode are given in the reference pages 
for _setvideomode. The _setvideomoderows function also specifies the number of text 
rows to be used in a text mode. If the constant_MAXTEXTROWS is specified for the rows 
argument, the function will choose the maximum number of rows available. In text modes, 
this is 50 rows on VGA, 43 on EGA, and 25 on others. In graphics modes that support 30 
or 60 rows, MAXTEXTROWS specifies 60 rows. 


The setvideomoderows function returns the numbers of rows set. The function returns 0 if 
an error occurred (e.g., if the mode is not supported). 


O ANS! M& DOS MOS QO UNIX OO XENIX 


In OS/2, only text video modes may be selected by _setvideomoderows. 


_getvideoconfig, _settextrows, _setvideomode 


dHinclude <stdlib.h> 
#Hinclude <conio.h> 
#Hinclude <graph.h> 


void main() 


{ 


struct videoconfig config; 
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/* Set 43-line graphics mode if available. */ 
if( !_setvideomoderows( _ERESCOLOR, 43 ) ) 
( 
_outtext( "EGA or VGA required” ); 
exit( 1 ); 
} 
_getvideoconfig( &config ); 


/* Set logical origin to center and draw a rectangle. */ 
_setlogorg( config.numxpixels / 2 - 1, config.numypixels / 2 - 1 ); 
_rectangle( _GBORDER, -8@, -50, 88, 5@ ); 


—getch(); 
_setvideomode( _DEFAULTMODE ); 
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Description Moves the view-coordinate origin to the specified physical point. 
#include <graph.h> 
struct xycoord far _setvieworg( short x, short y ); 
x,y New origin point 
Remarks The _setvieworg function moves the view-coordinate origin (0, 0) to the physical point 


(x, y). All other view-coordinate points move the same direction and distance. 


The xycoord structure, defined in GRAPH.H, contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


C 5.1 Difference This function replaces the _setlogorg function. 


Return Value The function returns the physical coordinates of the previous view origin in an xycoord 
structure, defined in GRAPH.H. 


Compatibility O ANS! M@ DOS OF OS7?2 QO UNIX OC XENIX 


See Also _getphyscoord, getviewcoord, _getwindowcoord, _setcliprgn, _setviewport 


Example 


/* SVORG.C: This program sets the view origin to the center of 
* the screen, then draws a rectangle using the new origin. 
* / 


#Hinclude <stdlib.h> 
#Hinclude <conio.h> 
#Finclude <graph.h> 


void main() 
{ 
struct videoconfig config; 
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/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 

_getvideoconfig( &config ); 


/* Set view origin to the center of the screen. */ 
_setvieworg( config.numxpixels / 2, config.numypixels / 2 ); 
_rectangle( _GBORDER, -8@, -50, 80, 508 ); 


getch(); 
_setvideomode( _DEFAULTMODE ); 
, ; 


_setviewport 688 


Description Creates a viewport. 
#include <graph.h> 


eo void far _setviewport( short x/, short y/, short x2, short y2 ); 


xl, yl Upper-left corner of viewport 
x2, y2 Lower-right comer of viewport 
Remarks The _setviewport function redefines the graphics viewport. The _setviewport function 


defines a clipping region in exactly the same manner as _setcliprgn, and then sets the 
view-coordinate origin to the upper-left corner of the region. The physical points (x/, y/) 
and (x2, y2) are the diagonally opposed corners of the rectangular clipping region. Any 
window transformation done with the _setwindow function applies only to the viewport 
and not to the entire screen. 


Return Value None. 
Compatibility O ANS! @ DOS OF OS UO UNIX O XENIX 


See Also _Setcliprgn, _setvieworg, _setwindow 


Example 


/* SVIEWPRT.C: This program sets. a viewport and then draws a rectangle 
* around it and an ellipse in it. 
*) 


#Finclude <conio.h> 
dHinclude <stdlib.h> 
#Hinclude <graph.h> 


void main() 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_setviewport( 100, 100, 200, 200 ); 
_rectangle( _GBORDER, @, @, 100, 180 ); 
—ellipse( _GFILLINTERIOR, 10, 10, 98, 98 ); 
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getch(); 
_setvideomode( _DEFAULTMODE ); 
} 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Sets the visual page. 

#include <graph.h> 

short far _setvisualpage( short page ); 

page Visual page number 


For hardware configurations that have an EGA or a VGA and enough memory to support 
multiple-screen pages, the _setvisualpage function selects the current visual page. The 
page argument specifies the current visual page. The default page number is 0. 


The function returns the number of the previous visual page. If the function fails, it returns 
a negative value. 


O ANS! M@ DOS OF O0S/72 O UNIX OO XENIX 
_getactivepage, _getvisualpage, _setactivepage, _setvideomode 


See the example for _setactivepage. 
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Description Defines a graphics window. 
#include <graph.h> 


short far _setwindow( short finvert, double wx/, double wy/, double wx2, 


double wy2 ); 
finvert Invert flag 
wxl, wyl Upper-left corner of window 
wx2, wy2 Lower-right comer of window 
Remarks The _setwindow function defines a window bounded by the specified coordinates. The 


arguments (wx/, wy/) specify the upper-left corner of the window, and the arguments 
(wx2, wy2) specify the lower-right corner of the window. 


The finvert argument specifies the direction of the coordinates. If finvert is TRUE, the 
y axis increases from the screen bottom to the screen top (Cartesian coordinates). If 
finvert is FALSE, the y axis increases from the screen top to the screen bottom (screen 
coordinates). . 


Any window transformation done with the _setwindow function applies only to the view- 
port and not to the entire screen. 


If wxl equals wx2 or wy/ equals wy2, the function will fail. 


Note that this function does not affect the output of presentation-graphics text (e.g., labels, 
axis marks, etc.). It also does not affect the output of the font display routine _outgtext. 


Return Value The function returns a nonzero value if successful. If the function fails (e.g., if it is not ina 
graphics mode), it returns 0. 


Compatibility O ANS| @ DOS Oos2 O UNKX OC XENIX 


See Also _setviewport 


Example 


™ 
+ 


SWINDOW.C: This program illustrates translation between window, 
* view, and physical coordinates. Functions used include: 
_Ssetwindow _getwindowcoord 

_getphyscoord _getviewcoord_wxy 


ee 
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#include <conio.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 


enum boolean { FALSE, TRUE }; 
enum display { MOVE, DRAW, ERASE }; 


void main() 


{ 


struct xycoord view, phys; 

struct _wxycoord oldwin, newwin; 

struct videoconfig vc; 

double xunit, yunit, xinc, yinc; 

short color, key, fintersect = FALSE, fdisplay = TRUE; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXRESMODE ) ) 
exTte a 3 

_getvideoconfig( &vc ); 


/* Set a window using real numbers. */ 
_setwindow( FALSE, -125.@, -100.0, 125.0, 100.2 ); 


/* Calculate the size of one pixel in window coordinates. 
* Then get the current window coordinates and color. 


ay 

oldwin = _getwindowcoord( 1, 1 ); 

newwin = _getwindowcoord( 2, 2 ); 

xunit = xinc = newwin.wx - oldwin.wx; 
yunit = yinc = newwin.wy - oldwin.wy; 
newwin = oldwin = _getcurrentposition_w(); 
color = _getcolor(); 
while( 1 ) 


( 
/* Set flag according to whether current pixel is on, then 
* turn pixel on. 


*/ 

if( _getpixel_w( oldwin.wx, oldwin.wy ) == color ) 
fintersect = TRUE; 

else 


fintersect = FALSE; 
_setcolor( color ); 
_setpixel_w( oldwin.wx, oldwin.wy ); 
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/* Get and test key. */ 
key = getch(); 
switch( key ) 
{ 
case 27: /* ESC Quit */ 
_setvideomode( _DEFAULTMODE. ); 
exit( @ ); 
case 32: /* SPACE Move no color */ 
fdisplay = MOVE; 
continue; 
case @: /* Extended code - get next */ 
key = getch(); 
switch( key ) 
{ 
case 72: /* UP -y */ 
newwin.wy -= yinc; 
break; 
case 77: /* RIGHT +X */ 
newwin.wx += xinc; 
break; 
case 8@: /* DOWN +y x] 
newwin.wy t= yinc; 
break; : 2% 
case 75: /* LEFT -X */ 
newwin.wx -= xinc; 
break; 
case 82: /* INS Draw white */ 
fdisplay = DRAW; 
continue; 
case 83: /* DEL Draw black */ 
fdisplay = ERASE; 
continue; 
} 
break; 
} 


/* Translate window coordinates to view, view to physical. 

* Then check physical to make sure we're on screen. Update screen 

* and position if we are. Ignore if not. 

*/ 

view = _getviewcoord_wxy( &newwin ); 

phys = _getphyscoord( view.xcoord, view.ycoord ); 

if( (phys.xcoord >= @) && (phys.xcoord < vc.numxpixels) && 
(phys.ycoord >= @) && (phys.ycoord < vc.numypixels) ) 

( 
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/* If display on, draw to new position, else move to new. */ 
if( fdisplay != MOVE ) 
{ 

if( fdisplay == ERASE ) 

_setcolor( @ ); 

_lineto_w( newwin.wx, newwin.wy ); 
} 
else 
{ 

_setcolor( @ ); 

_moveto_w( newwin.wx, newwin.wy ); 


/* If there was no intersect, erase old pixel. */ 
if( !fintersect ) 
_setpixel_w( oldwin.wx, oldwin.wy ); 
} 


oldwin = newwin; 
} 
else 

newwin = oldwin; 
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Description Sets the current logical mode for line drawing. 

#include <graph.h> 

short far setwritemode( short action ); 

action ' Interaction with existing screen image 
Remarks The _setwritemode function sets the current logical write mode, which is used when draw- 


Return Value 


Compatibility 


See Also 


Example 


ing lines with the _lineto and rectangle functions. 


The action argument defines the write mode. The possible values are _GAND, GOR, 
_GPRESET, _GPSET, and __GXOR. See the description of the _putimage function for 
more details on these manifest constants. 


The _setwritemode function returns the previous write mode, or —1 if an error occurs. 
O ANS! #@ DOS OF os? QO UNIX OC XENIX 


_getwritemode, _grstatus, _lineto functions, _putimage functions, _ rectangle 
functions, _setcolor, _setlinestyle 


See the example for_getwritemode. 
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Description 


Remarks 


Sets interrupt signal handling. 
#include <signal.h> 


void ( *signal( int sig, void( *func )( int sig [, int subcode J] ) ) ) (int sig ); 


sig Signal value 
func Function to be executed 
subcode Optional subcode to the signal number 


The signal function allows a process to choose one of several ways to handle an interrupt 
signal from the operating system. 


The sig argument must be one of the manifest constants described in Table R.11 and de- 
fined in SIGNAL.H. 


Table R.11 Signals and Responses 


Value Modes Meaning Default Action 
SIGABRT Real, Abnormal termination Terminates the calling program 
protected with exit code 3 
SIGBREAK Protected CTRL+BREAK signal Terminates the calling program 
with exit code 3 
SIGFPE Real, Floating-point error Terminates the calling program 
protected with exit code 3 
SIGILL Real, Illegal instruction Terminates the calling program 
protected with exit code 3 
SIGINT Real, CTRL4+C signal Terminates the calling program 
protected with exit code 3 
SIGSEGV Real, Illegal storage access Terminates the calling program 
protected with exit code 3 
SIGTERM Real, Termination request Terminates the calling program 
protected with exit code 3 
SIGUSR1 Protected OS/2 process flag A Signal is ignored 
SIGUSR2 Protected OS/2 process flag B Signal is ignored 
SIGUSR3 Protected OS/2 process flag C Signal is ignored 


SIGUSR1, SIGUSR2, and SIGUSR3 are user-defined signals which can be sent by means of 
DosFlagProcess. For details, see Microsoft Operating System/2 Programmer’ s Reference. 
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Note that SIGILL, SIGSEGV, and SIGTERM are not generated under DOS and SIGSEGV 
is not generated under OS/2. They are included for ANSI compatibility. Thus, you may set 
signal handlers for these signals via signal, and you may also explicitly generate these sig- 
nals by calling raise. 


Note also that signal settings are not preserved in child processes created by calls to exec 
or spawn. The signal settings are reset to the default in the child process. 


The action taken when the interrupt signal is received depends on the value of func. The 
func argument must be either a function address or one of the manifest constants defined in 


SIGNAL.H and listed below: 
Value Meaning 
SIG_ACK Acknowledges receipt of a signal (OS/2 only). This constant 


is valid only if a user-defined signal handler is installed. Once 
a process receives a given signal, the operating system does 
not send any more signals of this type until it receives a 
SIG_ACK acknowledgment from the process. The operating 
system does not queue up signals of a given type; therefore, if 
more than one signal of a given type accumulates before the 
process returns a SIG_ACK value, only the most recent signal 
is sent to the process after the SIG_ACK value is received by 
the operating system. This option has no effect on which han- 
dler is installed for a given signal. The manifest constant 
SIG_ACK is not supported for SIGFPE signals. 


SIG_DFL Uses system-default response. The system-default response 
for all signals except SIGUSR1, SIGUSR2, and SIGUSR3 is to 
abort the calling program. The calling process is terminated 
with exit code 3, and control returns to DOS or OS/2. If the 
calling program uses stream I/O, buffers created by the run- 
time library are not flushed, but buffers created by the operat- 
ing system are flushed. The default response for SIGUSR1, 
SIGUSR2, and SIGUSR3 is to ignore the signal. 


SIG_ERR Ignores interrupt signal (OS/2 only). This constant is equiv- 
alent to SIG_IGN, except that any process that tries to send 
this signal receives an error. A process may use the raise func- 
tion to send a signal to itself. A different process may senda 
signal by means of the function DosFlagProcess (if the signal 
is SIGUSR1, SIGUSR2, or SIGUSR3) or by means of 
DosKillProcess (if the signal is SIGTERM). 


SIG_IGN Ignores interrupt signal. This value should never be given for 
SIGFPE, since the floating-point state of the process is left 
undefined. 
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Function address Installs the specified function as the handler for the given 
signal. 


For all signals except SIGFPE and SIGUSRX, the function is 
passed the sig argument SIGINT and executed. 


For SIGFPE signals, the function is passed two arguments; 
namely SIGFPE and the floating-point error code identifying 
the type of exception that occurred. 


For SIGUSR1, SIGUSR2, and SIGUSR3, the function is passed 
two arguments: the signal number and the argument furnished 
by the DosFlagProcess function. 


For. SIGFPE, the function pointed to by func is passed two arguments, SIGFPE and an 
integer error subcode, FPE_xxx; then the function is executed. (See the include file 
FLOAT.H for definitions of the FPE_xxx subcodes.) The value of func is not reset upon re- 
ceiving the signal. To recover from floating-point exceptions, use setjmp in conjunction 
with longjmp. (See the example under _fpreset.) If the function returns, the calling 
process resumes execution with the floating-point state of the process left undefined. 


If the function returns, the calling process resumes execution immediately following the 
point at which it received the interrupt signal. This is true regardless of the type of signal 
or operating mode. 


Before the specified function is executed under DOS versions 3.x or earlier, the value 

of func is set to SIG_DFL. The next interrupt signal is treated as described above for 
SIG_DFL, unless an intervening call to signal specifies otherwise. This allows the program 
to reset signals in the called function. 


Under OS/2, the signal handler is not reset to the system-default response. Instead, no sig- 
nals of a given type are received by a process until the process sends a SIG_ACK value to 
the operating system. The program can restore the system-default response from the han- 
dler by first sending SIG_DFL and then sending SIG_ACK to the operating system. 


Since signal-handler routines are normally called asynchronously when an interrupt oc- 
curs, it is possible that your signal-handler function will get control when a C run-time 
operation is incomplete and in an unknown state. Certain restrictions therefore apply to the 
C functions that can be used in your signal-handler routine: 


1. Do not issue low-level or standard input and output routines (e.g., printf, read, write, 
and fread). — 


2. Do not call heap routines or any routine that uses the heap routines (e.g., malloc, 
strdup, putenv). 


3. Do not use any C function that generates a system call (e.g., getcwd, time). 
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Return Value 


Compatibility 
See Also 


Example 


4. Do not use the longjmp function unless the interrupt is caused by a floating-point ex- 
ception (i.e., sig is SIGFPE). In this case, the program should first reinitialize the 
floating-point package by means of a call to _fpreset. 


5. Do not use any overlay routines. 


The signal function returns the previous value of func associated with the given signal. For 
example, if the previous value of func was SIG_IGN, the return value will be SIG_IGN. 
The one exception to this rule is SIG_ACK, which returns the address of the currently in- 
stalled handler. 


A return value of —1 indicates an error, and errno is set to EINVAL. The possible error 
causes are an invalid sig value, an invalid func value (that is, a value that is less than 
SIG_ACK but not defined), or a func value of SIG_ACK used when no handler is currently 
installed. ‘ 


MANS! @ DOS MM OS/2 WM UNIX’ MB XENIX 


abort, exec functions, exit, exit, fpreset, spawn functions 


/* STGNAL.C. illustrates setting up signal interrupt routines. Functions 
illustrated include signal and raise. 


uses conditionals to use system-level DOS and OS/2 services. Another 


* 
* 
* Since C I/O functions are not safe inside signal routines, the code 
* 
* 
* 


option is to set global flags and do any I/O operations outside the 
signal handler. To compile the OS/2 version, define the symbol 0S2. 


dHinclude <stdio.h> 
#Hinclude <conio.h> 
fHinclude <signal.h> 
#Hinclude <process.h> 
dHinclude <stdlib.h> 
dif defined( 0S2 ) 
#define INCL_NOCOMMON 
dtdefine INCL_NOPM 
#tdefine INCL_VIO 
#tdefine INCL_KBD 
#Hinclude <os2.h> 
#include <string.h> 


itelse 


#Hinclude <dos.h> 
#Hinclude <bios.h> 


ffendif 
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void ctrichandler( void ); /* Prototypes */ 
void safeout( char *str ); 
int safein( void ); 


void main() 
( 
int ch; 


/* Modify CTRL+C behavior. */ 
if( signal( SIGINT, ctrichandler ) == SIG_ERR ) 
{ 
fprintf( stderr, "Couldn't set SIGINT\n" ); 
abort(); 
} 


/* Input loop illustrates results. */ 
do 
{ 
ch = getch(); 
if( ch == @ ) 
{ 
ch = getch(); 
if( ch == 46 ) /* Treat ALT+C like CTRL+C */ 
raise( SIGINT ); 
else . 
printf( “Extended code: %X\n", ch ); 


else 
printf( "ASCII code: %X\n", ch ); 
} while( ch != 27 ); /* ESC code */ 


} 


/* Handles SIGINT (CTRL+C) interrupt. */ 
void ctrichandler() 
( 

int c; 

char str{] =" "; 


/* Disallow CTRL+C during handler. */ 
signal( SIGINT, SIG_IGN ); 


safeout( "User break - abort processing? " ); 
.c¢ = safein(); 
str([@] = c; - 
safeout( str ); 
safeout( "\r\n" ); 
if( (c == ty") [| (c == 'Y') ) 
abort(); 
else 
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/* The CTRL+C interrupt must be reset to our handler since 
* by default it is reset to the system handler. 
*/ 
Signal( SIGINT, ctrichandler ); 
} 


/* Outputs a string using system level calls. */ 
void safeout( char *str ) 
{ 
#Hif defined( OS2 ) 
VioWrtTTY( str, strlen( str ), @ ); 
#felse 
union REGS inregs, outregs; 


inregs.h.ah = Ox@e; 
while( *str ) 
( 
inregs.h.al = *str++; 
jnt86( 0x10, &inregs, &outregs ); 
} 
dtendif 
} 


/* Inputs a character using system level calls. */ 
int safein() 
{ 
#Hif defined( OS2 ) 
KBDKEYINFO kki; 


KbdCharIn( &kki, IO_WAIT, @ ); 

return kki.chChar; 
Helse 

return _bios_keybrd( _KEYBRD_READ ) & Oxff; 
dtendif 
} 


Output 


ASCII code: 74 

ASCII code: 68 

ASCII code: 65 

AC 

User break - abort processing? n 
ASCII code: 62 

ASCII code: 1B 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Calculate sines and hyperbolic sines. 
#include <math.h> 


double sin( double x ); 

double sinh( double x ); 

long double sinl( long double x ); 
long double sinhl( long double x ); 


x Angle in radians 


The sin and sinh functions find the sine and hyperbolic sine of x, respectively. The sinl 


and sinhl functions are the 80-bit counterparts and use an 80-bit, 10-byte coprocessor form 
of arguments and return values. See the reference page on the long double functions for 
more details on this data type. 


The sin functions return the sine of x. If x is large, a partial loss of significance in the result 
may occur, and sin generates a PLOSS error. If x is so large that significance is completely 
lost, the sin function prints a TLOSS message to stderr and returns 0. In both cases, errno 
is set to ERANGE. 


The sinh function returns the hyperbolic sine of x. If the result is too large, sinh sets errno 
to ERANGE and returns t{HUGE_VAL. 


sin, sinh 
BANS! 9 DOS #8 OS/2 @ UNIX’ =f XENIX 
sinl, sinhl 


O ANS! @ DOS # OS72 QO UNIX O XENIX 


acos functions, asin functions, atan functions, cos functions, tan functions 


/* SINCOS.C: This program displays the sine, hyperbolic sine, cosine, 
* and hyperbolic cosine of pi / 2. 


ne 
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dHinclude <math.h> 
dHinclude <stdio.h> 


void main() 

{ 
double pi = 3.1415926535; 
double x, y; 


x= pi / 2; 

y = sin( x ); 

printf( “sin( 4f ) = @f\n", x, y ); 
y = sinh( x ); 
printf( "“sinh( 2f ) = %f\n",x, y ); 
y = cos( x ); 

printf( "cos( *f ) = @f\n", x, y )3 
y = cosh( x )3 

printf( “cosh( 2f ) = &f\n",x, y ); 


Output 


sin( 1.570796 ) = 1.980000 
sinh( 1.578796 ) = 2.301299 
cos( 1.570796 ) = 0.008000 
cosh( 1.570796 ) = 2.589178 
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Description 


Remarks 


Opens a file for file sharing. 


#include <fentl.h> 
#include <sys\types.h> 


#include <sys\stat.h> 
#include <share.h> 


#include <io.h> Required only for function declarations 


int sopen( char “filename, int oflag, int shflag [[, int pmode ]| ); 


filename File name 

oflag Type of operations allowed 
shflag Type of sharing allowed 
pmode Permission setting 


The sopen function opens the file specified by filename and prepares the file for sub- 
sequent shared reading or writing, as defined by oflag and shflag. The integer expression 
oflag is formed by combining one or more of the following manifest constants, defined in 
the file FCNTL.H. When two or more constants are used to form the argument oflag, the 
constants are combined with the OR operator (| ). . 


Constant Meaning 


O_APPEND Repositions the file pointer to the end of the file before every 
write operation. 


O_BINARY Opens file in binary (untranslated) mode. (See fopen for a de- 
scription of binary mode.) 


O_CREAT Creates and opens a new file. This has no effect if the file 
specified by filename exists. 


O_EXCL Returns an error value if the file specified by filename exists. 
This applies only when used with O_CREAT. 


O_RDONLY Opens file for reading only. If this flag is given, neither the 
O_RDWR flag nor the O_WRONLY flag can be given. 


O_RDWR Opens file for both reading and writing. If this flag is given, 
neither O_RDONLY nor O_WRONLY can be given. 
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O_TEXT Opens file in text (translated) mode. (See fopen for a descrip- 
tion of text mode.) 


O_TRUNC Opens and truncates an existing file to 0 bytes. The file must 
have write permission; the contents of the file are destroyed. 


O_WRONLY Opens file for writing only. If this flag is given, neither 
O_RDONLY nor O_RDWR can be given. 


The argument shflag is a constant expression consisting of one of the following manifest 
constants, defined in SHARE.H. If SHARE.COM (or SHARE.EXE for some versions of 
DOS) is not installed, DOS ignores the sharing mode. (See your system documentation for 
detailed information about sharing modes.) 


Constant Meaning 

SH_COMPAT Sets compatibility mode (not available in OS/2). This is the 
sharing mode used in the open function in DOS. 

SH_DENYRW Denies read and write access to file. 

SH_DENYWR Denies write access to file. 

SH_DENYRD Denies read access to file. 

SH_DENYNO Permits read and write access. This is the sharing mode used 


in the open function in OS/2. 


The sopen function should be used only under OS/2 and DOS versions 3.0 and later. 
Under earlier versions of DOS, the shflag argument is ignored. 


The pmode argument is required only when O_CREAT is specified. If the file does not 
exist, pmode specifies the file’s permission settings, which are set when the new file is 
closed for the first time. Otherwise, the pmode argument is ignored. The pmode argument 
is an integer expression that contains one or both of the manifest constants S_TWRITE and 
S_IREAD, defined in SYS\STAT.H. When both constants are given, they are combined 
with the OR operator (|). The meaning of the pmode argument is as follows: 


Value Meaning 
S_IWRITE Writing permitted 
S_IREAD Reading permitted 


S_IREAD | S_IWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. Under DOS and OS/2, all files are 
readable; it is not possible to give write-only permission. Thus, the modes S_IWRITE and 
S_IREAD | S_IWRITE are equivalent. 
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Return Value 


Compatibility 
See Also 


Example 


Note that under DOS versions 3.x with SHARE installed, a problem occurs when opening 
a new file with sopen under the following sets of conditions: 


@ With oflag set to O_CREAT | O_RDONLY or O_CREAT | WRONLY, pmode set to 
S_IREAD, and shflag set to SH_COMPAT. 


@ With oflag set to any combination that includes O_CREAT | O_RDWR, etre set to 
S_IREAD, and shflag set to anything other than SH_COMPAT. 


In either case, the operating system will prematurely close the file during system calls 
made within sopen, or the system will generate a sharing violation (INT 24H). To avoid 
the problem, open the file with pmode set to S IWRITE. After closing the file, call chmod 
and change the mode back to S_IREAD. Another solution is to open the file with pmode 
set to S_IREAD, oflag set to O_ CREAT | O_RDWR, and shflag set to SH_COMPAT. 


The sopen function applies the current file-permission mask to pmode before setting the 
permissions (see umask). 


The sopen function returns a file handle for the opened file. A return value of —1 indicates 
an error, and errno is set to one of the following values: 


Value Meaning 


EACCES Given path name is a directory; or the file is read-only but an 
open for writing was attempted; or a sharing violation oc- 
curred (the file’s sharing mode does not allow the specified 
operations; OS/2 and DOS versions 3.0 and later only). 


EEXIST The O_CREAT and O_EXCL flags are specified, but the 
named file already exists. 


EINVAL An invalid oflag or shflag argument was given. 
EMFILE No more file handles available (too many open files). 
ENOENT File or path name not found. 
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close, creat, fopen, _fsopen, open, umask 


See the example for locking. 
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Description Create and execute a new child process. 
#include <stdio.h> 
#include <process.h> 
int spawnl( int mode, char *cmdname, char *arg0, char *arg/, ... char *argn, NULL ); 
int spawnle( int mode, char *cmdname, char *arg0, char *arg/,... char *argn, NULL, 
char **envp ); 
int spawnlp( int mode, char *cmdname, char *arg0, char *arg/, ... char *argn, NULL); 
int spawnlpe( int mode, char *cmdname, char *arg0, char *arg/, ... char *argn, NULL, 
char **envp ); 
int spawnv( int mode, char *cmdname, char **argv ); 
int spawnve( int mode, char *cmdname, char **argyv, char **envp ); 
int spawnvp( int mode, char *cmdname, char **argyv )3 
int spawnvpe( int mode, char *cmdname, char **argv, char **envp ); 
mode Execution mode for parent process 
cmdname Path name of file to be executed 
arg, ... argn List of pointers to arguments 
argv Array of pointers to arguments 
envp Array of pointers to environment settings 
Remarks The spawn family of functions creates and executes a new child process. Enough memory 


must be available for loading and executing the child process. The mode argument deter- 
mines the action taken by the parent process before and during spawn. The following 
values for mode are defined in PROCESS.H: 


Value Meaning 


P_DETACH Continues to execute the parent process; child process is run 
in the background with no access to the console or keyboard. 
Calls to wait and cwait against the child process will fail. 
This is an asynchronous detached spawn and is valid only in 
OS/2 protected mode. 
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P_NOWAIT Continues to execute parent process concurrently with child 
process (asynchronous spawn, valid only in protected mode). 


P_ NOWAITO Continues to execute parent process and ignores wait and 
cwait calls against child process (asynchronous spawn, valid 
only in protected mode). 


P_OVERLAY Overlays parent process with child, destroying the parent 
(same effect as exec calls). 


P_WAIT Suspends parent process until execution of child process is 
complete (synchronous spawn). 


' The cmdname argument specifies the file which will be executed as the child process, and 
can specify a full path (from the root), a partial path (from the current working directory), 
or just a file name. If cmdname does not have a file-name extension or does not end witha 
period (.), the spawn function first tries the .COM extension, then the .EXE extension, and 
finally the .BAT extension (or, in OS/2 protected mode, the .CMD extension). This ability 
to spawn batch files is a new feature in Microsoft C version 6.0. 


If cmdname has an extension, only that extension is used. If cmdname ends with a period, 
the spawn calls search for cmdname with no extension. The spawnlp, spawnlpe, 
spawnvp, and spawnvpe routines search for cmdname (using the same procedures) in the 
directories specified by the PATH environment variable. 


If cmdname contains a drive specifier or any slashes (i.e., if it is a relative path name), the 
spawn call searches only for the specified file and no path searching is done. 


Arguments for the Child Process 


Arguments are passed to the child process by giving one or more pointers to character 
strings as arguments in the spawn call. These character strings form the argument list for 
the child process. The combined length of the strings forming the argument list for the 
child process must not exceed 128 bytes in real mode. The terminating null character (’\0’) 
for each string is not included in the count, but space characters (suromarically inserted to 
separate arguments) are included. 


The argument pointers may be passed as separate arguments (spawnl, spawnle, spawnlp, 
and spawnlpe) or as an array of pointers (Spawnv, spawnve, spawnvp, and spawnvpe). 
At least one argument, arg0 or argv[0], must be passed to the child process. By conven- 
tion, this argument is the name of the program as it might be typed on the command line 
by the user. (A different value will not produce an error.) In real mode, the argv[0] value is 
supplied by the operating system and is the fully qualified path name of the executing pro- 
gram. In protected mode, it is usually the program name as it would be typed on the com- 
mand line. | 
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The spawnl, spawnle, spawnlp, and spawnlpe calls are typically used in cases where the 
number of arguments is known in advance. The arg0 argument.is usually a pointer to 
cmdname. The arguments arg/ through argn are pointers to the character strings forming 
the new argument list. Following argn, there must be a NULL pointer to mark the end of 
the argument list. 


The spawnv, spawnve, spawnvyp, and spawnvype calls are useful when the number of ar- 
guments to the child process is variable. Pointers to the arguments are passed as an array, 
argv. The argument argv[0] is usually a pointer to a path name in real mode or to the pro- 
gram name in protected mode, and argv[1] through argy[n] are pointers to the character 
strings forming the new argument list. The argument argv[7+1] must be a NULL pointer to 
mark the end of the argument list. 


Environment of the Child Process 


Files that are open when a spawn call is made remain open in the child process. In the 
spawnl, spawnlp, spawnv, and spawnvp calls, the child process inherits the environment 
of the parent. The spawnle, spawnlpe, spawnve, and spawnvpe calls allow the user to 
alter the environment for the child process by passing a list of environment settings 
through the envp argument. The argument envp is an array of character pointers, each ele- 
ment of which (except for the final element) points to a null-terminated string defining an 
environment variable. Such a string usually has the form 


NAME=value 


where NAME is the name of an environment variable and value is the string value to which 
that variable is set. (Note that value is not enclosed in double quotation marks.) The final 
element of the envp array should be NULL. When envp itself is NULL, the child process in- 
herits the environment settings of the parent process. 


The spawn functions can pass the child process all information about open files, including 
the translation mode, through the C_FILE_INFO entry in the environment that is passed in 
real mode (_C_FILE_INFO in protected mode). 


The C start-up code normally processes this entry and then deletes it from the environ- 
ment. However, if a spawn function spawns a non-C process (such as CMD.EXE), this 
entry remains in the environment. Printing the environment shows graphics characters in 
the definition string for this entry, since the environment information is passed in binary 
form in real mode. It should not have any other effect on normal operations. In protected 
mode, the environment information is passed in text form and therefore contains no 
graphics characters. 


You must explicitly flush (using fflush or flushall) or close any stream prior to the spawn 
function call. 
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Starting with Microsoft C version 6.0, you can control whether or not the open file infor- 
mation of a process will be passed to its child processes. The external variable _fileinfo 
(declared in STDLIB.H) controls the passing of C_LFILE_INFO information. If _fileinfo is 
0, the C_FILE_INFO information is not passed to the child processes. If _fileinfo is not 0, 
C_FILE_INFO is passed to child processes. . 


By default, _fileinfo is 0 and thus the C_FILE_INFO information is not passed to child 
processes. There are two ways to modify the default value of _fileinfo: 


m@ Link the supplied object file FILEINFO.OBJ into your program. Use the /NOE option 
to avoid multiple symbol definitions. 


m™ Set the _fileinfo variable to a nonzero value directly within your C program. 


Return Value The return value from a synchronous spawn (P_WAIT specified for mode) is the exit sta- 
tus of the child process. 


The return value from an asynchronous spawn (P_NOWAIT or P_NOWAITO specified for 
mode) is the process ID. To obtain the exit code for a process spawned with P_ NOWAIT, 
you must call the wait or cwait function and specify the process ID. The exit code cannot 
be obtained for a process spawned with P_ NOWAITO. 


The exit status is 0 if the process terminated normally. The exit status can be set to a non- 
zero value if the child process specifically calls the exit routine with a nonzero argument. 
If the child process did not explicitly set a positive exit status, a positive exit status indi- 
cates an abnormal exit with an abort or an interrupt. A return value of —1 indicates an 
error (the child process is not started). In this case, errno is set to one of the following 


values: 

Value Meaning 

E2BIG In DOS, the argument list exceeds 128 bytes, or the space 
required for the environment information exceeds 32K. In 
OS/2, the argument list and the space required for environ- 
ment information combined exceed 32K. 

EINVAL The mode argument is invalid. 

ENOENT The file or path name is not found. 

ENOEXEC The specified file is not executable or has an invalid 
executable-file format. 

ENOMEM Not enough memory is available to execute the child process. 


Note that signal settings are not preserved in child processes created by calls to spawn 
routines. The signal settings are reset to the default in the child process. 
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Compatibility O ANS! @ DOS # OS/ OF UNIX OO XENIX 
The spawn functions, with POVERLAY mode, will not work in OS/2 DOS- 
compatibility mode in programs which are bound with FAPI for dual-mode execution. 
Programs linked as DOS mode .EXE files will work, and protected-mode programs will 
work. The restriction applies only to bound programs in real mode. 
In order to ensure proper overlay initialization and termination, do not use the setjmp or 
longjmp functions to enter or leave an overlay routine. 
See Also abort, atexit, exec functions, exit, exit, onexit, system 
Example 


/* SPAWN.C: This program accepts a number in the range 1 - 8 from the 

* command line. Based on the number it receives, it executes one of the 
* eight different procedures that spawn the process named child. For 

* some of these procedures, the CHILD.EXE file must be in the 

* same directory; for others, it only has to be in the same path. 


#Hinclude <stdio.h> 
#Hinclude <process.h> 


char *my_env[] = 


{ 


“THI S=environment will be", 
"PASSED=to child.exe by the", 
"SPAWNLE=and", 


"SPAWNLPE= 


and", 


“SPAWNVE=and", 


"SPAWNVPE= 


NULL 
}3 


functions", 


void main( int argc, char *argv{] ) 


{ 


char *args([4]; 
int result; 


/* Set up 
args({@] = 
args([1] 
args([2] = 
args[3] = 


parameters to be sent: */ 
[Clit bd 

"“spawn??"; 

"two"; 

NULL; 


switch (argvCl1J][@]) /* Based on first letter of argument */ 


{ 


case ‘l': 
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} 


spawnl( P_WAIT, argv(2], argv[2], "spawnl", "two", NULL ); 


break; 
case ‘'2': 


spawnle( P_WAIT, argv[2], argv[2], "Spawnle", "two", 


NULL, my_env ); 
break; 
case '3': 


spawnlp( P_WAIT, argv(2], argv[2], “Spawnlp", "two", NULL ); 


break; 
case '4'; 


spawnlpe( P_WAIT, argv[2], argv[2], “spawnlpe", "two", 


NULL, my_env ); 
break; 
case '5';: 
spawnv( P_OVERLAY, argv({2], args ); 
break; 
case '6': 
spawnve( P_OVERLAY, argv[2], args, my_env ); 
break; 
case '/': 
spawnvp( P_OVERLAY, argv[2], args ); 
break; 
case '8': 
spawnvpe( P_OVERLAY, argv({2], args, my_env ); 
break; 
default: 


printf( "SYNTAX: SPAWN <1-8> <childprogram>\n" ); 


exit( 1 ); 


printf( "\n\nReturned from SPAWN!\n" ); 
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Description Breaks a path name into components. 

#include <stdlib.h> 

void _splitpath( char *path, char *drive, char *dir, char *fname, char *ext ); 

path Full path name 

drive Drive letter 

dir Directory path 

jname File name 

ext File extension 
Remarks The _splitpath routine breaks a full path name into its four components. The path argu- 


Return Value 


Compatibility 


ment should point to a buffer containing the complete path name. The maximum size nec- 
essary for each buffer is specified by the manifest constants _MAX_DRIVE, MAX_DIR, 
_MAX_FNAME, and _MAX EXT, defined in STDLIB.H. The other arguments point to the 
buffers used to store the path-name elements: 


Buffer Description 

drive Contains the drive letter followed by a colon (:) if a drive is 
specified in path. 

dir Contains the path of subdirectories, if any, including the trail- 


ing slash. Forward slashes (/ ), backslashes (\), or both may 
be present in path. 


fname Contains the base file name without any extensions. 
ext Contains the file-name extension, if any, including the leading 
period (.). 


The return parameters will contain empty strings for any path-name components not found 
in path. 


None. 
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See Also _fullpath, _makepath 
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/* MAKEPATH.C */ 
dHinclude <stdlib.h> 
dHinclude <stdio.h> 


void main() 
{ 
char path_buffer[l_MAX_PATH]; 
char drive[_MAX_DRIVE]; 
char dirL_MAX_DIR]; 
char fname[_MAX_FNAME]; 
char ext{_MAX_EXT]; 


_makepath( path_buffer, "c", "\\c6@\\clibref\\", "“makepath", "c" ); 
printf( "Path created with _makepath: %s\n\n", path_buffer ); 
_splitpath( path_buffer, drive, dir, fname, ext ); 

printf( "Path extracted with _splitpath:\n" ); 

printf( " Drive: %s\n", drive ); 

printf( " Dir: %s\n", dir ); 

printf( " Filename: %s\n", fname ); 

printf( " Ext: %s\n", ext ); 


Output 
Path created with _makepath: c:\c6@\clibref\makepath.c 


Path extracted with _splitpath: 
Drive: c: 
Dir: \c6@\clibref\ 
Filename: makepath 
Ext: .c 
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Description Writes formatted data to a string. 

#include <stdio.h> 

int sprintf( char *buffer, const char *format [, argument] ... )3 

buffer Storage location for output 

format Format-control string 

argument Optional arguments 
Remarks The sprintf function formats and stores a series of characters and values in buffer. Each 


Return Value 


Compatibility 


See Also 


Example 


argument (if any) is converted and output according to the corresponding format specifica- 
tion in the format. The format consists of ordinary characters and has the same form and 
function as the format argument for the printf function. (See printf for a description of the 
format and arguments.) A null character is appended to the end of the characters written, 
but is not counted in the return value. 


The sprintf function returns the number of characters stored in buffer, not counting the 
terminating null character. 
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fprintf, printf, sscanf 


/* SPRINTF.C: This program uses sprintf to format various data and 
* place them in the string named buffer. 
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dHinclude <stdio.h> 


void main() 


{ 


char buffer[200], s[] = "computer", c= ere 
int 1 355.9% 
float fp = 1.7320534; 
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/* Format and print various data: */ 

j = sprintf( buffer, "\tString: aSs\n", S )3 

j += sprintf( buffer + j, "“\tCharacter: %c\n", c ); 

j += sprintf( buffer + j, "\tInteger: %d\n", i ); 

j t= sprintf( buffer + j, "\tReal: Zf\n", fp ); 


printf( "Output:\n%s\ncharacter count = 4d\n", buffer, j ); 


Output 

Output: 
String: computer 
Character: 1 
Integer: 35 
Real: 1.732053 


character count = 71 
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Description Calculates the square root. 
#include <math.h> 


double sqrt( double x ); 
long double sqrtl( long double + ); 


x Nonnegative floating-point value 


Remarks The sqrt functions calculate the square root of x. The sqrtl function is the 80-bit counter- 
part and uses an 80-bit, 10-byte coprocessor form of arguments and return values. 


Return Value The sqrt functions return the square-root result. If x is negative, the function prints a 
DOMAIN error message to stderr, sets errno to EDOM, and returns 0. 


Error handling can be modified by using the matherr or _matherrlI routine. 
Compatibility MANS! M@ DOS #8 OS/2 MW UNIX’ WB XENIX 


See Also exp, log, matherr, pow 


Example 


/* SQRT.C: This program calculates a square root. */ 
#include <math.h> 

#Hinclude <stdio.h> 

#Hinclude <stdlib.h> 


void main() 
double question = 45.35, answer; 


answer = sqrt( question ); 
if( errno == EDOM ) 
printf( “Domain error\n" ); 
else 
printf( "The square root of %4.2f is %.2f\n", question, answer ); 


Output 


The square root of 45.35 is 6.73 
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Description Sets a random starting point. 

#include <stdlib.h> | Required only for function declarations 

void srand( unsigned int seed ); 

seed Seed for random-number generation 


Remarks The srand function sets the starting point for generating a series of pseudorandom in- 
tegers. To reinitialize the generator, use 1 as the seed argument. Any other value for seed 
sets the generator to a random starting point. 


The rand function is used to retrieve the pseudorandom numbers that are generated. Call- 
ing rand before any call to srand will generate the same sequence as calling srand with 
seed passed as 1. . 


Return Value None. 
Compatibility M@ ANS! & DOS #8 OS/72 UNIX’ 8 XENIX 


See Also rand 


Example 


/* RAND.C: This program seeds. the random number generator with the 
* time, then displays 20 random integers. 
Bad 


dFinclude <stdlib.h> 
dHinclude <stdio.h> 
#Hinclude <time.h> 


void main() 


( 


int i; 


/* Seed the random number generator with current time so that 
* the numbers will be different: every time we run. 

* / : 

srand( (unsigned)time( NULL ) ); 
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/* Display 18 numbers. */ 
for( i = @; i < 10; i++ ) 
printf( “ %6d\n", rand() ); 
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Description Reads formatted data from a string, 
#include <stdio.h> 


int sscanf( const char “buffer, const char *format [, argument]... )3 


buffer Stored data 
format Format-control string 
argument Optional arguments 
Remarks The sscanf function reads data from buffer into the locations given by each argument. 


Every argument must be a pointer to a variable with a type that corresponds to a type speci- 
fier in format. The format controls the interpretation of the input fields and has the same 
form and function as the format argument for the scanf function; see scanf for a complete 
description of format. 


Return Value The sscanf function returns the number of fields that were successfully converted and as- 
signed. The return value does not include fields that were read but not assigned. 


The return value is EOF for an attempt to read at end-of-string. A return value of 0 means 
that no fields were assigned. 


Compatibility MANS! @ DOS # OS/2 M UNIX’ Wf XENIX 


See Also fscanf, scanf, sprintf 


Example 


/* SSCANF.C: This program uses sscanf to read data items from 
* a string named tokenstring, then displays them. 
ad 


dHinclude <stdio.h> 


void main() 

{ 
char tokenstring[] = "15 12 14..."; 
char s[81]; 
char c; 
int 7; 
float fp; 
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/* Input various data from tokenstring: */ 
sscanf( tokenstring, “%s", s ); 

sscanf( tokenstring, “%c", &c ); 

sscanf( tokenstring, “%d", &i ); 

sscanf( tokenstring, "%f", &fp ); 


/* Output the data read */ 
printf( "String s\n", s ) 


printf( “Character = %c\n", c ); 
printf( “Integer: = %4d\n", i ); 
printf( "Real: = 2f\n", fp ); 


Output 


String = 15 
Character = 1 
Integer: 15 

Real: 15 .GB000G 
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Description Gets the size of the stack available. 
#include <malloc.h> Required only for function declarations 
size_t stackavail( void ); 


Remarks The stackavail function returns the approximate size (in bytes) of the stack space available 
for dynamic memory allocation with alloca. 


Return Value The stackavail function returns the size in bytes as an unsigned integer value. 
Compatibility O ANS! @ DOS #@ OS/ OF UNIX O XENIX 
Example 


/* ALLOCA.C: This program checks the stack space available before 
* and after using the alloca function to allocate space on the stack. 
ies 


#Hinclude <malloc.h> 
fHinclude <stdio.h> 


void main() 
{ 
char *buffer; 


printf( "Bytes available on stack: Zu\n", stackavail() ); 


/* Allocate memory for string. */ 

buffer = alloca( 120 * sizeof( char ) ); 
printf( "Enter a string: " ); 

gets( buffer ); 

printf( “You entered: %s\n", buffer ); 


printf( "Bytes available on stack: %u\n", stackavail() )3; 


Output 


-Bytes available on stack: 2028 

Enter a string: How much stack space will this string take? 
You entered: How much stack space will this string take? 
Bytes available on stack: 1982 
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Description Gets status information on a file. 

#include <sys\stat.h> 

#include <sys\types.h> 

int stat( char “pathname, struct stat *buffer ); 

pathname Path name of existing file 

buffer Pointer to structure that receives results 
Remarks The stat function obtains information about the file or directory specified by pathname 


and stores it in the structure pointed to by buffer. The stat structure, defined in the file 
SYS\STAT.H, includes the following fields: 


Field Value 

st_atime Time of last modification of file (same as st_mtime and 
st_ctime). 

st_ctime Time of last modification of file (same as st_atime and 
st_mtime). 

st_dev Drive number of the disk containing the file (same as 


st_rdev). Real mode only. 


st_mode Bit mask for file-mode information. The S_IFDIR bit is set if 
pathname specifies a directory; the S_IFREG bit is set if 
pathname specifies an ordinary file. User read/write bits are 
set according to the file’s permission mode; user execute bits 
are set according to the file-name extension. 


st_mtime Time of last modification of file (same as st_atime and 
st_ctime). 

st_nlink Always I. 

st_rdev Drive number of the disk containing the file (same as st_dev). 


Real mode only. 


st_size Size of the file in bytes. 


Note that if pathname refers to a device, the size and time fields in the stat structure are 


not meaningful. 
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Return Value The stat function returns the value 0 if the file-status information is obtained. A return 
value of —1 indicates an error; also, errno is set to ENOENT, indicating that the file name 
or path name could not be found. 


Compatibility O ANS! M@ DOS MOS MH UNIX Mi XENIX 
See Also access, fstat 
Example 


/* STAT.C: This program uses the stat function to report information 
* about the file named STAT.C. 
mf 


dHinclude <time.h> 
#Hinclude <sys\types.h> 
fHinclude <sys\stat.h> 
#Hinclude <stdio.h> 


void main() 
{ 
struct stat buf; 
int fh, result; 
char buffer[] = "A line to output"; 


/* Get data associated with "stat.c": */ 
result = stat( "“stat.c", &buf ); 


/* Check if statistics are valid: */ 
if( result !=@ ) 
perror( "Problem getting information" ); 
else 
{ 
/* Output some of the statistics: */ 
printf( "File size : 1d\n", buf.st_size ); 
printf( "Drive : Zc:\n", buf.st_dev + ‘A’ ); 
printf( "Time modified : %s", ctime( &buf.st_atime ) ); 


Output 
File size : 761 
Drive Pa Oi 


Time modified : Wed Jun 14 12:20:08 1989 
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Description Gets the floating-point status word. 
| #include <float.h> 
unsigned int _status87( void ); 


Remarks The _status87 function gets the floating-point status word. The status word is a com- 
bination of the 8087/80287/80387 status word and other conditions detected by the 
8087/80287/80387 exception handler, such as floating-point stack overflow and underflow. 


Return Value The bits in the value returned indicate the floating-point status. See the FLOAT.H include 
file for a complete definition of the bits returned by _status87. 


Note that many of the math library functions modify the 8087/80287 status word, with un- 
predictable results. Return values from _clear87 and _status87 become more reliable as 
fewer floating-point operations are performed between known states of the floating- pout 
status word. 


Compatibility O ANS! @ DOS MOS? O UNIX O XENIX 


See Also _clear87, _control87 


Example 


/* STATUS87.C: This program creates various floating-point errors and 
* then uses _status87 to display messages indicating these problems. 
Lad 


#Finclude <stdio.h> 
fHinclude <float.h> 


void main() 

{ 
double a = le-4@, b; 
float x, y; 


printf( "Status = %.4x - clear\n",_status87() ); 


/* Assignment into y is inexact & underflows: */ 
y = a; 
printf( "Status = %.4x - inexact, underflow\n", _status87() ); 


/* y is denormal: */ 
b= y; 
printf( “Status = %.4x - inexact underflow, denormal\n", _status87() ); 
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/* Clear user 8087: */ 
_clear87(); 
} 


Output 
Status = @000 - clear 


Status = 0030 - inexact, underflow 
Status = 0032 - inexact underflow, denormal 


727 Streat, _fstreat 


i a 
Description Append a string. 
#include <string.h> Required only for function declarations 


char *streat( char *string/, const char *string2 ); 


char far * far _fstreat( char _far *string], const char _far *string2 ); 


stringl Destination string 
string2 Source string 
Remarks The streat and _fstreat functions append string2 to string!, terminate the resulting string 


with a null character, and return a pointer to the concatenated string (string/). 


The streat and _fstrcat functions operate on null-terminated strings. The string arguments 
to these functions are expected to contain a null character (?\0’) marking the end of the 
string. No overflow checking is performed when strings are copied or appended. 


The _fstrcat function is a model-independent (large-model) form of the strcat function. 
The behavior and return value of _fstreat are identical to those of the model-dependent 
function streat, with the exception that the arguments and return values are far pointers. 


Return Value The return values for these functions are described above. 


Compatibility strcat 
MANS! @ DOS HH OS/2 UNIX Wi XENIX 
_fstrcat 
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See Also strncat, strncmp, strncpy, strnicmp, strrchr, strspn 


Example 


/* STRCPY.C: This program uses strcpy and strcat to build a phrase. */ 


#Hinclude <string.h> 
#Hinclude <stdio.h> 
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void main() 
{ 
char string[8Q]; 


strcpy( string, "Hello world from " ); 
strceat( string, “strepy " ); 

strcat( string, “and " ); 

strcat( string, “strcat!" ); 

printf( "String = %s\n", string ); 


Output 


String = Hello world from strcpy and strcat! 
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Strehr, _fstrehr 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Find a character ina string. 
#include <string.h> Required only for function declarations 


char *strchr( const char *string, int c ); 


char far * far _fstrchr( const char _far *string, int c ); 


string Source string 


é Character to be located 


The strchr and _fstrchr functions return a pointer to the first occurrence of c in string. 
The character c may be the null character (\0’); the terminating null character of string is 
included in the search. The function returns NULL if the character is not found. 


The strehr and _fstrchr functions operate on null-terminated strings. The string argu- 
ments to these functions are expected to contain a null character (’\0’) marking the end of 
the string. 


The _fstrchr function is a model-independent (large-model) form of the strehr function. 
The behavior and return value of _fstrchr are identical to those of the model-dependent 
function strchr, with the exception that the arguments and return values are far. 


The return values for these functions are described above. 


strchr 
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_fstrchr 
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strespn, strncat, strncmp, strnepy, strnicmp, strpbrk, strrchr, strspn, strstr 


/* STRCHR.C: This program illustrates searching for a character with 
* strchr (search forward) or strrchr (search backward). 


ie 


#Hinclude <string.h> 
#Hinclude <stdio.h> 
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int ch='r'; 

char string[] = "The quick brown dog jumps over the lazy fox"; 

char fmtl1(]j = sf 1 2 3 4: 5"; 
char fmt2£] = "12345678901234567890123456789812345678981234567898" ; 


void main() 

{ 
char *pdest; 
int result; 


printf( "String to be searched: \n\t\t%s\n", string ); 
printf( "\t\t%s\n\t\t%s\n\n", fmtl, fmt2 ); 
printf( "Search char:\t%c\n", ch ); 


/* Search forward. */ 
pdest = strchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "Result:\tfirst %c found at position 4d\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


/* Search backward. */ 
pdest = strrchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( “Result:\tlast %c found at position %d\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


Output 


String to be searched: 
The quick brown dog jumps over the lazy fox 
1 2 3 4 5 
12345678981234567890123456789012345678901234567890 


Search char: r 
Result: first r found at position 12 


Result: last r found at position 30 


731 Stremp, _fstremp 
Description Compare strings. 

#include <string.h> Required only for function declarations 

int stremp( const char “string/, const char *string2 ); 

int far _fstremp( const char _far *string/, const char _far *string2 ); 

string] String to compare 

string2 String to compare 
Remarks The stremp and __fstremp functions compare string] and string2 lexicographically and re- 


Return Value 


Compatibility 


turn a value indicating their relationship, as follows: 


Value Meaning 

<0 string] less than string2 
=0 string] identical to string2 
>0 Stringl greater than string2 


The stremp and _fstremp functions operate on null-terminated strings. The string argu- 
ments to these functions are expected to contain a null character (’\0’) marking the end of 
the string. 


The _fstremp function is a model-independent (large-model) form of the stremp function. 


_ The behavior and return value of _fstremp are identical to those of the model-dependent 


function stremp, with the exception that the arguments are far pointers. 


The strcmpi and stricmp functions are case-insensitive versions of strcmp. 
The return values for these functions are described above. 


strcmp 
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See Also memcmp, memicmp, strncat, strncmp, strncpy, strnicmp, strrchr, strspn 


Example 


/* STRCMP.C */ 
#Hinclude <string.h> 
#Hinclude <stdio.h> 


char string1[] 
char string2[] 


"The quick brown dog jumps over the lazy fox"; 
"The QUICK brown dog jumps over the lazy fox"; 


void main() 

{ 
char tmp[20]; 
int result; 


/* Case sensitive */ 
printf( “Compare strings:\n\t%s\n\t%s\n\n", stringl, string2 ); 
result = stremp( stringl, string2 ); 
if( result > @ ) 
strcpy( tmp, “greater than" ); 
else if( result < @ ) 
strcpy( tmp, "less than" ); 
else 
strcpy( tmp, “equal to" ); 
printf( "\tstrcemp: String 1 is %s string 2\n", tmp ); 


/* Case insensitive (could use equivalent stricmp) */ 
result = strempi( stringl, string2 ); 
if( result > @ ) 
strcpy( tmp, "greater than" ); 
else if( result < @ ) 
strcpy( tmp, “less than" ); 
else 
strcpy( tmp, “equal. to" ); 
printf( "\tstrcmpi: String 1 is %s string 2\n", tmp ); 


Output 


Compare strings: 
The quick brown dog jumps over the lazy fox 
The QUICK brown dog jumps over the lazy fox 


strcmp: String 1 is greater than string 2 
strempi: String 1 is equal to string 2 
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Streoll 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Compares strings using locale-specific information. 
#include <string.h> Required only for function declarations 
int strcoll( const char *string/, const char *string2 ); 


string] String to compare 


string2 String to compare 


The strcoll function compares string] and string2 lexicographically and returns a value in- 
dicating their relationship, as follows: 


Value Meaning 

<0 string] less than string2 
=0 string] identical to string2 
>0 string] greater than string2 


The strcoll function operates on null-terminated strings. The string arguments to these 
functions are expected to contain a null character (’\0’) marking the end of the string. 


The strcoll function differs from stremp in that it uses locale-specific information to pro- 
vide locale-specific collating sequences. 
The return value for this function is described above. 


MANS! @ DOS WM OS OF UNIX OF XENIX 


localecony, setlocale, strcmp, strncmp, strxfrm 


Strepy, _fstrcpy | 1 734 


Description 


Remarks 


Return Value | 


Compatibility 


See Also 


Example 


Copy a string. 
#include <string.h> Required only for function declarations 


char *strepy( char *string], const char *string2 ); 


char _far* far _fstrepy( char _far *string], const char _far *string2 ); 


string] Destination string 


string2 Source string 


The strepy function copies string2, including the terminating null character, to the loca- 
tion specified by string/, and returns string. 


The strepy and _fstrcpy functions operate on null-terminated strings. The string argu- 
ments to these functions are expected to contain a null character (°\0’) marking the end of 
the string. No overflow checking is performed when strings are copied or appended. 


The _fstrcpy function is a model-independent (large-model) form of the strepy function. 
The behavior and return value of _fstrepy are identical to those of the model-dependent 
function strepy, with the exception that the arguments and return values are far pointers. 


The return values for these functions are described above. 


strcpy 
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_fstrepy 
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strcat, strcmp, strncat, strncmp, strncpy, strnicmp, strrchr, strspn 


/* STRCPY.C: This program uses strcpy and strcat to build a phrase. */ 


#Hinclude <string.h> 
#Hinclude <stdio.h> 
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void main() 
{ 
char string[8@]; 


strcepy( string, “Hello world from " ); 
streat( string, “strcpy “ ); 

streat( string, “and " ); 

streat( string, "“strcat!" ); 

printf( “String = %s\n", string ); 


Output 


String = Hello world from strcpy and strcat! 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Find a substring in a string. 
#include <string.h> Required only for function declarations 


size_t strcspn( const char *string/, const char *string2 ); 


size.t far fstrespn( const char far *string/, const char _far *string2 ); 


string] Source string 


string2 Character set 


The strespn functions return the index of the first character in string/ belonging to the set 
of characters specified by string2. This value is equivalent to the length of the initial sub- 
string of string] consisting entirely of characters not in string2. Terminating null charac- 
ters are not considered in the search. If string/ begins with a character from string2, 
strcespn returns 0. 


The strespn and _fstrespn functions operate on null-terminated strings. The string argu- 
ments to these functions are expected to contain a null character (’\0’) marking the end of 
the string. 


The _fstrespn function is a model-independent (large-model) form of the strespn func- 
tion. The behavior and return value of _fstrespn are identical to those of the model- 
dependent function strespn, with the exception that the arguments and return values 
are far. 


The return values for these functions are described above. 


strcespn 
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_fstrespn 
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strncat, strnemp, strncpy, strnicmp, strrchr, strspn 
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/* STRCSPN.C -*/ 


fHinclude <string.h> 
dHinclude <stdio.h> 


737 Strespn, _fstrespn 


void main() 

{ 
char string[] = "xyzabc"; 
int pos; 


pos = strcspn( string, “abc” ); 
printf( "First a, b or c in %s is at character %4d\n", string, pos ); 


Output 


First a, b or c in xyzabc is at character 3 
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Description Copies a date to a buffer. 
#include <time.h> 


char *_strdate( char *datestr ); 


datestr Current date 
Remarks The _strdate function copies the date to the buffer pointed to by datestr, formatted 
mm/dd/yy 


where mm is two digits representing the month, dd is two digits representing the day of 
the month, and yy is the last two digits of the year. For example, the string 


12/05/88 


represents December 5, 1988. 


The buffer must be at least nine bytes long. 
Return Value The _strdate function returns a pointer to the resulting text string datestr. 
Compatibility O ANSI @ DOS # OS/ O UNIX OO XENIX 
See Also asctime, ctime, gmtime, localtime, mktime, time, tzset 


Example 


/* STRTIME.C */ 
#Hinclude <time.h> 
dHinclude <stdio.h> 


void main() 

{ 
char dbuffer [9]; 
char tbuffer [9]; 


_Strdate( dbuffer ); 
printf( "The current date is %s \n", dbuffer ); 
_strtime( tbuffer ); 
printf( "The current time is %s \n", tbuffer ); 


739 _Strdate 
Output 


The current date is 06/28/89 
The current time is 09:33:13 


strdup Functions 740 


Description 


Remarks 


Return Value 


Compatibility 


Duplicate strings. 
#include <string.h> Required only for function declarations 


char *strdup( const char *string ); 
char far * far _fstrdup( const char _far *string ); 


char _near* _far_nstrdup( const char _far *string ); 
string Source string 


The strdup function allocates storage space (with a call to malloc) for a copy of string and 
returns a pointer to the storage space containing the copied string. The function returns 
NULL if storage cannot be allocated. 


The _fstrdup and _nstrdup functions provide complete control over the heap used for 
string duplication. The strdup function returns a pointer to a copy of the string argument. 
The space for the string is allocated from the heap specified by the memory model in use. 
In large-data models (that is, compact-, large-, and huge-model programs), strdup allo- 
cates space from the far heap. In small-data models (tiny-, small-, and medium-model pro- 
grams), strdup allocates space from the near heap. 


The strdup, _fstrdup, and _nstrdup functions operate on null-terminated strings. The 
string arguments to these functions are expected to contain a null character (’\0’) marking 
the. end of the string. 


The _fstrdup function returns a far pointer to a copy of the string allocated in far memory 
(the far heap). As with the other model-independent functions, the syntax and semantics of 
these functions correspond to those of strdup except for the sizes of the arguments and re- 
turn values. The _nstrdup function returns a near pointer to a copy of the string allocated 
in the near heap (in the default data segment). 


The return values for these functions are described above. 


strdup, _fstrdup, _nstrdup 


O ANS! @ DOS WM OS/7 O UNIX OO XENIX 
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See Also strcat, strcmp, strncat, strncmp, strnepy, strnicmp, strrchr, strspn 


Example 


/* STRDUP.C. */ 
#include <string.h> 
dHinclude <stdio.h> 
#Hinclude <conio.h> 
#Hinclude <dos.h> 


void main() 

{ 
char buffer[] = "This is the buffer text"; 
char *newstring; 


printf ( "Original: s\n", buffer ); 


newstring = strdup( buffer ); 
printf( “Copy: s\n", newstring ); 


Output 


Original: This is the buffer text 
Copy: This is the buffer text 
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Description 


Remarks 


Gets a system error message (strerror) or prints a user-supplied error message (_strerror). 
#include <string.h> Required only for function declarations 


char *strerror( int errnum ); 


char *_strerror( char *string ); 


errnum Error number 


string -  User-supplied message 


The strerror function maps errnum to an error-message string, returning a pointer to the 
string. The function itself does not actually print the message; for that, you need to call an 
output function such as printf. 


If string is passed as NULL, _strerror returns a pointer to a string containing the system 
error message for the last library call that produced an error. The error-message string is 
terminated by the newline character (’\n’). 


If string is not equal to NULL, then _strerror returns a pointer to a string containing (in 
order) your string message, a colon, a space, the system error message for the last library 
call producing an error, and a newline character. Your string message can be a maximum 
of 94 bytes long. 


Unlike perror, strerror alone does not print any messages. To print the message re- 
turned by _strerror to stderr, your program will need an fprintf statement, as shown in 
the following lines: 


if ((access("datafile",2)) == -1) 
fprintf(_strerror(NULL)); 


The actual error number for _strerror is stored in the variable errno, which should be de- 
clared at the external level. The system error messages are accessed through the variable 
sys_errlist, which is an array of messages ordered by error number. The _strerror func- 
tion accesses the appropriate error message by using the errno value as an index to the 
variable sys_errlist. The value of the variable sys_nerr is defined as the maximum num- 
ber of elements in the sys_errlist array. 


To produce accurate results, strerror should be called immediately after a library routine 
returns with an error. Otherwise, the errno value may be overwritten by subsequent calls. 


Note that the _strerror function under Microsoft C version 5.0 is identical to the version 
4.0 strerror function. The name was altered to permit the inclusion in Microsoft C version 
5.0 of the ANSI-conforming strerror function. The _strerror function is not part of the 
ANSI definition but is instead a Microsoft extension to it; it should not be used where 
portability is desired. For ANSI compatibility, use strerror instead. 


743 strerror, _strerror 


Return Value The strerror function returns a pointer to the error-message string. The string can be over- 
written by subsequent calls to strerror. 


The _strerror function returns no value. 


Compatibility strerror 


MANS! @ DOS MOS QO UNIX O XENIX 


_Strerror 


O ANS! #@ DOS HW OS/72 O UNIX O XENIX 
See Also clearerr, ferror, perror 


Example See the example for perror. 
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Description Formats a time string. 
#include <time.h> Required only for function declarations 


size_t strftime( char *string, size_t maxsize, const char *format, 
const struct tm *timeptr ); 


string Output string 
maxsize Maximum length of string 
format Format control string 
timeptr tm data structure 

Remarks The strftime function formats the tm time value in timeptr according to the supplied 
format argument and stores the result in the buffer string. At most, maxsize characters are 
placed in the string. 


The format argument consists of one or more codes; as in printf, the formatting codes are 
preceded by a % sign. Characters that do not begin with a % sign are copied unchanged to 
string. The LC_TIME category of the current locale affects the output formatting of 
strftime. 


The formatting codes for strftime are listed below: 


Format Description 

Joa | Abbreviated weekday name 

TA Full weekday name 

%b Abbreviated month name 

%B Full month name : 

Joc Date and time representation appropriate for the locale 
%d Day of the month as a decimal number (01 — 31) 
%H Hour in 24-hour format (00 — 23) 

%ol Hour in 12-hour format (01 — 12) 

Jj Day of the year as a decimal number (001 — 366) 
Jom Month as a decimal number (01 — 12) 


%M Minute as a decimal number (00 — 59) 


745 


sirftime 


Return Value 


Compatibility 
See Also 


Example 


%op Current locale’s AM/PM indicator for a 12-hour clock 

%S Second as a decimal number (00-61) | 

%U Week of the year as a decimal number; Sunday is taken as the 
first day of the week (00 — 53) 

Jow Weekday as a decimal number (0 — 6; Sunday is 0) 

TW Week of the year as a decimal number; Monday is taken as 
the first day of the week (00 — 53) 

%ox Date representation for current locale 

TX Time representation for current locale . 

%oy Year without the century as a decimal number (00 — 99) 

%Y Year with the century as a decimal number 

%z Fime zone name or abbreviation; no characters if time zone is 
unknown 

%% Percent sign 


The strftime function returns the number of characters placed in string if the total number 
of resulting characters, including the terminating null, is not more than maxsize. 
Otherwise, strftime returns 0, and the contents of the string are indeterminate. 

M ANS! M@ DOS HW OS/72 QO UNIX OC XENIX 


localeconv, setlocale, strxfrm 


See the example for perror. 


Stricmp, _fstricmp 746 


Description Compare strings without regard to case. 
#include <string.h> Required only for function declarations 


int stricmp( const char *string/], const char *string2 ); 


int far _fstricmp( const char far *string/, const char _far *string2 ); 


string] String to compare 
string2 String to compare 
Remarks The stricmp and _fstricmp functions compare string] and string2 lexicographically and 


return a value indicating their relationship, as follows: 


Value Meaning 

<0 string] less than string2 
=0 stringl identical to string2 
>0 string! greater than string2 


The stricmp and _fstricmp functions operate on null-terminated strings. The string argu- 
ments to these functions are expected to contain a null character (’\0’) marking the end of 
the string. 


The _fstricmp function is a model-independent (large-model) form of the stricmp func- 
tion. The behavior and return value of _fstricmp are identical to those of the model- 
dependent function stricmp, with the exception that the arguments are far pointers. 


The stremp function is a case-sensitive version of stricmp. 
Return Value The return values for these functions are described above. 


Compatibility stricmp 
O ANS! @ DOS WM OS/2 MW UNIX’ Wf XENIX 
_fstricmp : 
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See Also memcmp, memicmp, strcat, strcpy, strncat, strncmp, strncpy, strnicmp, strrchr, 
Strset, strspn 


Example See the example for strcmp. 


strlen, _fstrlen | 748 


Description 


Remarks 


Return Value 


Compatibility 


Example 


/* STRLEN.C */ 


Get the length of a string. 
#include <string.h> Required only for function declarations 


size_t strlen( const char *string ); 


size_t _fstrlen( const char _far *string ); 
string Null-terminated string 


The strlen and _fstrlen functions return the length in bytes of string, not including the ter- 
minating null character (’\0’). 


The _fstrlen function is a model-independent (large-model) form of the strlen function. 
The behavior and return value of _fstrlen are identical to those of the model-dependent 
function strlen, with the exception that the argument is a far pointer. 


These functions return the string length. There is no error return. 


strlen 
MANS! M@ DOS M@ OS/2 HW UNIX’ WB XENIX 
_fstrien 
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dtinclude <string.h> 
#Hinclude <stdio.h> 
##include <conio.h>~ 
#Hinclude <dos.h> 


749 | Strlen, _fstrlen 


void main() 

{ 
char buffer[61} = "How long am I?"; 
int Ten; 


len = strlen( buffer ); 


printf( “'%s' is %d characters long\n", buffer, len ); 
} 


Output 


"How long am I?' is 14 characters long 


Strlwr, _fsirlwr | | | 750 


Description Convert a string to lowercase. 
#include <string.h> Required only for function declarations 


char *strlwr( char “string ); 


char far* far _fstrlwr( char far *string ); 
string String to be converted 


Remarks The strlwr and _fstrlwr functions convert any uppercase letters in the given null- 
terminated string to lowercase. Other characters are not affected. 


The _fstrlwr function is a model-independent (large-model) form of the strlwr function. 
The behavior and return value of _fstrlwr are identical to those of the model-dependent 
function strlwr, with the exception that the argument and return values are far pointers. 


Return Value These functions return a pointer to the converted string. There is no error return. 
Compatibility O ANS! @ DOS HW OS/2 O UNIX OO XENIX 


See Also strupr 


Example 


/* STRLWR.C: This program uses striwr and strupr to create 
* uppercase and lowercase copies of a mixed-case string. 
mf 


dHinclude <string.h> 
dHinclude <stdio.h> 


void main() 

{ 
char string{198] = "The String to End All Strings!"; 
char *copyl, *copy2; 


copyl = strlwr( strdup( string ) ); 
copy2 = strupr( strdup( string ) ); 
printf( "Mixed: %s\n", string ); 
printf( "Lower: %s\n", copyl ); 
printf( "Upper: %s\n", copy2 ); 
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Output 


Mixed: The String to End All Strings! 
Lower: the string to end all strings! 
Upper: THE STRING TO END ALL STRINGS! 


strneat, _fsirncat 752 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


/* STRNCAT.C */ 


Appends characters of a string. 
#include <string.h> Required only for function declarations 
char *strneat( char *string/, const char *string2, size_t count ); 


char far* far _fstrncat( char _far *string], const char _far *string2, 
size_t count ); 


string] Destination string 
string2 Source string 
count Number of characters appended 


The strncat and _fstrncat functions append, at most, the first count characters of string2 
to string/, terminate the resulting string with a null character (°\0’), and return a pointer to 
the concatenated string (string/). If count is greater than the length of string2, the length of 
string2 is used in place of count. 


The _fstrncat function is a model-independent (large-model) form of the strneat function. 
The behavior and return value of _fstrncat are identical to those of the model-dependent 
function strncat, with the exception that all the pointer arguments and return values are far 
pointers. 


The return values for these functions are described above. 


strncat 
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strcat, strcmp, strepy, strncmp, strncpy, strnicmp, strrchr, strset, strspn 


#include <string.h> 
dHinclude <stdio.h> 
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void main() 
{ 
char string[88] = “This is the initial string!"; 
char suffix{] = " extra text to add to the string..."; 


/* Combine strings with no more than 19 characters of suffix: */ 
printf( "Before: %s\n", string ); 

strncat( string, suffix, 19 ); 

printf( "After: ‘%s\n", string ); 


Output 


Before: This is the initial string! / 
After: This is the initial string! extra text to add 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Compare characters of two strings. 
#include <string.h> Required only for function declarations 


int strncmp( const char *string/, const char *string2, size_t count ); 


int far _fstrncmp( const char far *string], const char _far *string2, size_t count ); 


string] String to compare 
string2 String to compare 
count Number of characters compared 


The strncmp and _fstrnemp functions lexicographically compare, at most, the first count 
characters of string/ and string2 and return a value indicating the relationship between the 
substrings, as listed below: 


Value Meaning 

<0 . string] less than string2 

=0 string] equivalent to string2 
>0 string! greater than string2 


The strnicmp function is a case-insensitive version of strncmp. 


The _fstrncmp function is a model-independent (large-model) form of the strnemp func- 
tion. The behavior and return value of _fstrncemp are identical to those of the model- 
dependent function strnemp, with the exception that all the arguments and return values 
are far. 


The return values for these functions are described above. 


strncmp 


MANS! M@ DOS @ OS/2 MW UNIX Mi XENIX 


_fstrncmp 


O ANS! @ DOS WM oOS/2 O UNIX OC XENIX 


strceat, strcmp, strcpy, strncat, strncpy, strrchr, strset, strspn 
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strnemp, _fsirncmp 


Example a 


/* STRNCMP.C */ 


#Finclude <string.h> 


#Hinclude <stdio. 


char stringl[] = “The quick brown dog jumps over the lazy fox"; 
char string2[] = "The QUICK brown fox jumps over the lazy dog"; 


void main() 

{ 
char tmp(2Q]; 
int result; 


h> 


printf( "Compare strings: \n\t\t%s\n\t\t%s\n\n", stringl, 


printf( "Function:\tstrnemp (first 1@ characters only)\n" ); 


result = strncemp( stringl, string2 , 10 ); 


if( result > 


Q) 


strcpy( tmp, “greater than" ); 
else if( result < @ ) 
strcpy( tmp, “less than" ); 


else 


strcpy( tmp, “equal to" ); 
printf( "Result:\t\tString 1 is %s string 2\n\n", tmp ); 


printf( "Function:\tstrnicmp (first 18 characters 


result = strnicmp( stringl, string2, 10 ); 


if( result > 


0 ) 


strcpy( tmp, “greater than" ); 
else if( result < @ ) 
strcpy( tmp, “less than" ); 


else 


strcpy( tmp, “equal to" ); 
printf( "Result: \t\tString 1 is 4S string 2\n\n", tmp ); 


Output 


Compare strings: 


Function: 
Result: 


Function: 
Result: 


The quick brown dog jumps over the lazy fox 
The QUICK brown fox jumps over the lazy dog 


strncemp (first 10 characters only) 
String 1 is greater than string 2 


strnicmp (first 18 characters only) 
String 1 is equal to string 2 


only)\n" )3; 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Copy characters of one string to another. 
#include <string.h> Required only for function declarations 
char *strnepy( char *string/, const char *string2, size_t count ); 


char far * far _fstrnepy( char far *string/, const char _far *string2, 
size_t count ); 


string] Destination string 
string2 Source string 
count Number of characters copied 


The strnepy and _fstrnepy functions copy count characters of string2 to string] and re- 
turn string. If count is less than the length of string2, a null character (’\0’) is not ap- 
pended automatically to the copied string. If count is greater than the length of string2, the 
string] result is padded with null characters (°\0’) up to length count. 


Note that the behavior of strnepy and _fstrnepy is undefined if the address ranges of the 
source and destination strings overlap. 


The _fstrnepy function is a model-independent (large-model) form of the strnepy func- 
tion. The behavior and return value of _fstrnepy are identical to those of the model- 
dependent function strnepy, with the exception that all the arguments and return values 
are far. 


The return values for these functions are described above. 


strncpy 
MANS! M#& DOS M@ OS/2 UNIX HB XENIX 


_fstrncpy 


O ANS! @ DOS WM OS/2 OF UNIX OO XENIX 


strcat, strcmp, strepy, strncat, strncmp, strnicmp, strrchr, strset, strspn 
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Example 


/* STRNCPY.C */ 
#iinclude <string.h> 
dHinclude <stdio.h> 


void main() 


{ 
char string[190] = “Cats are nice usually"; 


printf("Before: %s\n", string ); 
strncpy( string, "Dogs", 4 ); 

strncpy( string + 9, “mean", 4 ); 
printf("After: -%s\n", string ); 


Output 


Before: Cats are nice usually 
After: Dogs are mean usually 
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Description 


| Remarks 


Return Value 
Compatibility 
_ See Also 


Example 


Compare characters of two strings without regard to case. 

#include <string.h> Required only for function declarations 

int strnicmp( const char *string/, const char *string2, size_t count ); 
int far _fstrnicmp( const char _far *string], const char _far *string2,. 


' size_t count ); 


string String to compare 


string2 String to compare 
count Number of characters compared 


The strnicmp and _fstrnicmp functions lexicographically compare (without regard to 
case), at most, the first count characters of string] and string2 and return a value indicating 
the relationship between the substrings, as listed below: 


Value Meaning 

<0 String! less than string2 

=0 string] equivalent to string2 
>0 »  stringl greater than string2 


The strncmp function is a case-sensitive version of strnicmp. 


The _fstrnicmp function is a model-independent (large-model) form of the strnicmp func- 
tion. The behavior and return value of _fstrnicmp are identical to those of the model- 
dependent function strnicmp, with the exception that all the arguments and return values 
are far. 


The return values for these functions are described above. 
O ANS! @ DOS #8 OS/72 O UNIX OO XENIX 
strcat, strcmp, strcpy, strncat, strnepy, strrchr, strset, strspn 


See the example for strncmp. 
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sirnset, _fsirnset 


Description 


Remarks 


Return Value 
Compatibility 
See Also 


Example 


/* STRNSET.C */ 


Initialize characters of a string to a given character. 
#include <string.h> Required only for function declarations 


char *strnset( char “string, int c, size_t count ); 


char far* far _fstrnset( char _far *string, int c, size_t count ); 


string String to be initialized 
c Character setting 
count Number of characters set 


The strnset and _fstrnset functions set, at most, the first count characters of string to the 
character c and return a pointer to the altered string. If count is greater than the length of 
String, the length of string is used in place of count. 


The _fstrnset function is a model-independent (large-model) form of the strnset function. 
The behavior and return value of _fstrnset are identical to those of the model-dependent 
function strnset, with the exception that all the arguments and return values are far. 


The return values for these functions are described above. 
O ANS! #& DOS #@ OS/72 OF UNIX O XENIX 


strcat, strcmp, strcpy, strset 


#Finclude <string.h> 
d#Finclude <stdio.h> 


void main() 


{ 


char string[15] = “This is a test"; 


/* Set not more than 4 characters of string to be *'s */ 
printf( "Before: %s\n", string ); 
strnset( string, '*', 4 ); 


printf( "After: %s\n", string ); 
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Output 


Before: This is a test 
After: **** js a test 
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Strpbrk, _ fstrpbrk 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


/* STRPBRK.C */ 


Scan strings for characters in specified character sets. 
#include <string.h> Required only for function declarations 


char *strpbrk( const char *string/, const char *string2 ); 


char far * far _fstrpbrk( const char _far *string], const char far *string2 ); 


string Source string 


string2 Character set 


The strpbrk function finds the first occurrence in string] of any character from string2. 
The terminating null character (’\0’) is not included in the search. 


The _fstrpbrk function is a model-independent (large-model) form of the strpbrk func- 
tion. The behavior and return value of _fstrpbrk are identical to those of the model- 
dependent function strpbrk, with the exception that all the arguments and return values 
are far. 


These functions return a pointer to the first occurrence of any character from string2 in 
string]. A NULL return value indicates that the two string arguments have no characters in 
common. 


strpbrk 
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_fstrpbrk 


O ANS! @ DOS HM OS/ O UNIX OO XENIX 


strehr, strrchr 


d#include <string.h> 
#Hinclude <stdio.h> 


void main() 


{ 3 


char string{[108] = "The 3 men and 2 boys ate 5 pigs\n"; 
char *result; 
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/* Return pointer to first ‘'a' or 'b' in “string” */ 
printf( "l: %s\n", string ); 

result = strpbrk( string, "8123456789" ); 

printf( "2: @s\n", resultt++ ); 

result = strpbrk( result, "@123456789" ); 

printf( "3: %s\n", result++ ); ° 

result = strpbrk( result, "@123456789" ); 

printf( "4: %s\n", result ); 


Output 

1: The 3 men and 2 boys ate 5 pigs 
2: 3 men and 2 boys ate 5 pigs 

3: 2 boys ate 5 pigs 


4: 5 pigs 
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Strrehr, _fstrrehr 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Scan a string for the last occurrence of a character. 
#include <string.h> Required only for function declarations 


char *strrchr( const char *string, int c ); 


char _far* far _fstrrchr( const char far “string, int c ); 


String - Searched string 


Cc Character to be located 


The strrchr function finds the last occurrence of the character c in string. The string’s ter- 
minating null character (’\0’) is included in the search. (Use strchr to find the first occur- 
rence of c in string.) 


_ The _fstrrchr function is a model-independent (large-model) form of the strrehr func- 


tion. The behavior and return value of _fstrrchr are identical to those of the model- 
dependent function strrehr, with the exception that all the pointer arguments and return 
values are far pointers. 


These functions return a pointer to the last occurrence of the character in the string. A 
NULL pointer is returned if the given character is not found. 


strrehr 
MANS! @ DOS MW OS/2 MW UNIX WB XENIX 
_fstrrcehr 


O ANS| @ DOS WM OS/2 © UNIX OC XENIX 


strchr, strespn, strncat, strncmp, strncpy, strnicmp, strpbrk, strspn 


/* STRCHR.C: This program illustrates searching for a character with 
* strchr (search forward) or strrchr (search backward). 


*/ 


#Hinclude <string.h> 
#Hinclude <stdio.h> 
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int ch= 'r'; 

char string{] = "The quick brown dog jumps over the lazy fox"; 

~ char fmtl[] = " 1 2 3 4 5 
char fmt2[] = "12345678901234567890123456789012345678901234567890" ; 


void main() 


char *pdest; 
int result; 


printf( “String to be searched: \n\t\t%s\n", string ); 
printf( "\t\t%s\n\t\t%s\n\n", fmtl, fmt2 ); 
printf( "Search char:\t%c\n", ch ); 


/* Search forward. */ 
pdest = strchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "Result:\tfirst %c found at position 4d\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


/* Search backward. */ 
pdest = strrchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "Result:\tlast %c found at position Zd\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


Output 


String to be searched: 
_ The quick brown dog jumps over the lazy fox 
1 2 | 4 5 
12345678981234567898123456789012345678901234567890 


Search char: r 
Result: first r found at position 12 


Result: last r found at position 38 
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a Ne IE a a eg ene 
Description Reverses characters of a string. 
#include <string.h> Required only for function declarations 


char *strrev( char *string ); 


char _far* far _fstrrev( char _far “string ); 
string String to be reversed 


Remarks The strrev function reverses the order of the characters in string. The terminating null 
character (?\0’) remains in place. 


The _fstrrev function is a model-independent (large-model) form of the strrev function. 
The behavior and return value of _fstrrev are identical to those of the model-dependent 
function strrev, with the exception that the argument and return value are far pointers. 


Return Value These functions return a pointer to the altered string. There is no error return. 
Compatibility O ANS! M@& DOS MOS O UNIX OO XENIX 


See Also strepy, strset 


Example 


/* STRREV.C: This program checks an input string to see whether it is a 
* palindrome: that is, whether it reads the same forward and backward. 
*/ 


#Hinclude <string.h> 
#Hinclude <stdio.h> 


void main() 
char string[100]; 
int result; 


printf( "Input a string and I will tell you if it is a palindrome:\n" ); 
gets( string ); 
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/* Reverse string and compare (ignore case): */ 
result = strempi( string, strrev( strdup( string ) ) ); 
if( result == @ ) 
printf( "The string \"%s\" is a palindrome\n\n", string ); 
else 
printf( "The string \"%s\" is not a palindrome\n\n", string ); 


Output 


Input a string and I will tell you if it is a palindrome: 
Able was I ere I saw Elba 
The string "Able was I ere I saw Elba" is a palindrome 
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Description Set characters of a string to a character. 
#include <string.h> Required only for function declarations 


char *strset( char *string, int c ); 


char far* far _fstrset( char far *string, int c ); 


string - String to be set 
c Character setting 

Remarks The strset function sets all of the characters of string to c, except the terminating null 
character (\0”). 


The _fstrset function is a model-independent (large-model) form of the strset function. 
The behavior and return value of _fstrset are identical to those of the model-dependent 
function strset, with the exception that the pointer arguments and return value are far 
pointers. 


Return Value These functions return a pointer to the altered string. There is no error return. 
Compatibility O ANS! @ DOS WM OS OF UNIX OO XENIX 


See Also memset, strcat, strcmp, strcpy, strnset 


Example 


/* STRSET.C */ 
#include <string.h> 
#tinclude <stdio.h> 


void main() 
{ 
char string(] = “Fill the string with something"; 


printf( "Before: %s\n", string ); 

strset( string, '*' ); 

printf( "After: %s\n", string ); 
} 
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Output 


Before: Fill the string with something 
After: KKKKEKRKEKRKEKEKEKKRKEKKKKEKKRKEREKEKKKKREE 
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Strspn, _fstrspn 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Find the first substring. 
#include <string.h> Required only for function declarations 


size_t strspn( const char *string/, const char *string2 ); 


size_t far _fstrspn( const char _far *string/, const char _far *string2 ); 


string] Searched string 


string2 Character set 


The strspn function returns the index of the first character in string] that does not belong 
to the set of characters specified by string2. This value is equivalent to the length of the ini- 
tial substring of string/ that consists entirely of characters from string2. The null character 
(’\0’) terminating string2 is not considered in the matching process. If string] begins with 
a character not in string2, strspn returns 0. 


The _fstrspn function is a model-independent (large-model) form of the strspn function. 
The behavior and return value of _fstrspn are identical to those of the model-dependent 
function strspn, with the exception that the arguments are far pointers. 


These functions return an integer value specifying the length of the segment in string con- 
sisting entirely of characters in string2. 


strspn 
MANS! M@ DOS # OS2 MW UNIX J XENIX 
_fstrspn 


O ANS! @ DOS # OS/72 QO UNIX OC XENIX 


strcspn, strncat, strncmp, strncpy, strnicmp, strrchr 


/* STRSPN.C: This program uses strspn to determine the length of 
* the segment in the string “cabbage” consisting of a's, b's, and c's. 
* In other words, it finds the first non-abc letter. 


a 


fFinclude <string.h> 
fHinclude <stdio.h> 
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void main() 


{ 
char string[] = “cabbage”; 
int result; 
result = strspn( string, “abc" ); 
printf( "The portion of '%s' containing only a, b, orc " 
"is 4d bytes long\n", string, result ); 
} 
Output 


The portion of ‘cabbage’ containing only a, b, or c is 5 bytes long 


1 | strstr, _fstrstr 


a a Le eee a a a EL 
Description Find a substring. 
#include <string.h> Required only for function declarations 


char *strstr( const char *string/, const char *string2 ); 


char _far* far _fstrstr( const char far *string], const char _far *string2 ); 


string Searched string 
string2 String to search for 
Remarks The strstr function returns a pointer to the first occurrence of string2 in string]. 


The _fstrstr function is a model-independent (large-model) form of the strstr function. 
The behavior and return value of _fstrstr are identical to those of the model-dependent 
function strstr, with the exception that the arguments and return value are far pointers. 


Return Value These functions return either a pointer to the first occurrence of string2 in string], or 
NULL if they do not find the string. 


Compatibility strstr 
@ ANS| @ DOS HM OS O UNIX QO XENIX 
_fstrstr 


O ANS! @ DOS # OS CO UNIX O XENI 
See Also strcspn, strncat, strncmp, strncpy, strnicmp, strpbrk, strrchr, strspn 


Example 


/* STRSTRGG FS 
#include <string.h> 
#Hinclude <stdio.h> 


char str{] = "lazy"; 
char string£] = “The quick brown dog jumps over the lazy fox"; 
char fmtl{] = . 1 2 3 4 5" 


char fmt20] = "12345678901234567890123456789812345678981234567890" ; 
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void main() 

( 
char *pdest; 
int result; 


printf( "String to be searched:\n\t%s\n", string ); 
printf( "\t%s\n\t%s\n\n", fmtl, fmt2 ); 


pdest = strstr( string, str ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "%s found at position %d\n\n", str, result ); 
else 


printf( "%s not found\n", str ); 


Output 


String to be searched: 
The quick brown dog jumps over the lazy fox 
1 2 3 


4 5 
12345678981234567898123456789012345678981234567890 


lazy found at position 36 


773 _Strtime 
Description Copies the time to a buffer. 

#include <time.h> 

char *_strtime( char *ftimestr ); 

timestr Time string 
Remarks The _strtime function copies the current time into the buffer pointed to by timestr. The 


Return Value 
Compatibility 


See Also 


Example 


(/* STRIIMNESG. */ 


time is formatted 
hh:mm:ss 


where hh is two digits representing the hour in 24-hour notation, mm is two digits repre- 
senting the minutes past the hour, and ss _ is two digits representing seconds. For ex- 
ample, the string 


18:23:44 


represents 23 minutes and 44 seconds past 6:00 PM. 


The buffer must be at least nine bytes long. 
The _Strtime function returns a pointer to the resulting text string timestr. 
O ANS! @ DOS MOS2 O UNIX OC XENIX 


asctime, ctime, gmtime, localtime, mktime, time, tzset 


dHinclude <time.h> 
dHinclude <stdio.h> 


void main() 


{ 


char dbuffer [9]; 
char tbuffer [9]; 
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_strdate( dbuffer ); 
printf( "The current date is %s \n", dbuffer ); 
_Strtime( tbuffer ); 
printf( “The current time is %s,\n", tbuffer ); 


Output 


The current date is 06/20/89 
The current time is 09:33:13 
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Striod, strtol, _strtold, strtoul 


Description 


Remarks 


Convert strings to a double-precision (strtod, _strtold), long-integer (strtol), or unsigned 
long-integer (strtoul) value. 


#include <stdlib.h> 


double strtod( const char *nptr, char **endptr ); 
long strtol( const char *nptr, char **endptr, int base ); 
long double _strtold( const char *nptr, char **endptr ); 


unsigned long strtoul( const char *nptr, char **endptr, int base ); 


nptr String to convert 
endptr End of scan 


base Number base to use 


The strtod, _strtold, strtol, and strtoul functions convert a character string to a double- 
precision value, a long-double value, a long-integer value, or an unsigned long-integer 
value, respectively. The input string is a sequence of characters that can be interpreted as a 
numerical value of the specified type. If the strtod or _strtold function appears in a 
compact-, large-, or huge-model program, nptr can be a maximum of 100 characters. 


These functions stop reading the string at the first character they cannot recognize as part 
of a number. This may be the null character (’\0’) at the end of the string. With strtol or 
strtoul, this terminating character can also be the first numeric character greater than or 
equal to base. If endptr is not NULL, a pointer to the character that stopped the scan is 
stored at the location pointed to by endptr. If no conversion could be performed (no valid 
digits were found or an invalid base was specified), the value of nptr is stored at the loca- 
tion pointed to by endptr. 


The strtod and __strtold functions expect nptr to point to a string with the following form: 
[whitespace] [sign] [digits] [[.digits] [ {d|Dlel E}[[sign]digits] 

The first character that does not fit this form stops the scan. 

The strtol function expects nptr to point to a string with the following form: 
[whitespace] [sign] [0] I{ x! X }]] [digits] 

The strtoul function expects nptr to point to a string having this form: 


[whitespace] [{ +! -}]] (OT I{ x 1X }]] {digits] 
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If base is between 2 and 36, then it is used as the base of the number. If base is 0, the ini- 
tial characters of the string pointed to by nptr are used to determine the base. If the first 
character is 0 and the second character is not ’x’ or ’X’, then the string is interpreted as an 
octal integer; otherwise, it is interpreted as a decimal number. If the first character is ’0’ 
and the second character is ’x’ or ’X’, then the string is interpreted as a hexadecimal in- 
teger. If the first character is ’1’ through ’9’, then the string is interpreted as a decimal in- 
teger. The letters ’a’ through ’z’ (or A’ through ’Z’) are assigned the values 10 through 
35; only letters whose assigned values are less than base are permitted. 


The strtoul function allows a plus (+) or minus (—) sign prefix; a leading minus sign indi- 
cates that the return value is negated. 


Return Value The strtod and _strtold functions return the value of the floating-point number, except 
when the representation would cause an overflow, in which case it returns -HUGE_VAL. 
' The functions return 0 if no conversion could be performed or an underflow occurred. 


The strtol function returns the value represented in the string, except when the repre- 
sentation would cause an overflow, in which case it returns LONG_MAX or LONG_MIN. 
The function returns 0 if no conversion could be performed. 


The strtoul function returns the converted value, if any. If no conversion can be per- 
formed, the function returns 0. The function returns ULONG_MAX on overflow. In all four 
functions, errno is set to ERANGE if overflow or underflow occurs. 


Compatibility strtod, strtol, strtold 


Mm ANS| M@ DOS & OS/7 HW UNIX’ MB XENIX 


strtoul 


@ ANS| WM DOS WM OS2 OF UNIX OC XENIX 


See Also atof, atol 


Example 


/* STRTOD.C: This program uses strtod to convert a string to a 
* double-precision value; strtol to convert a string to long 
* integer values; and strtoul to convert a string to unsigned 
* long-integer values. 

x 


dFinclude <stdlib.h> 
#Hinclude <stdio.h> 


"7 _ - trtod, strtol, _strtold, strtoul 


void main() 
{ 
char *string, *Stopstring; 
double x; 
long 1; 
int base; 
unsigned long ul; 


string = "3.1415926This stopped it"; 

x = strtod( string, &stopstring ); 

printf( “string = %s\n", string-); 

printf(" strtod = 2f\n", x ); 

printf(” Stopped scan at: %s\n\n", stopstring 


— 
we 


string = "-19110134932This stopped it"; 

1 = strtol( string, &stopstring, 10 ); 

printf( “string = %s\n", string ); 

printf("  strtol = 41d\n", 1 ); 

printt(" Stopped scan at: %s\n\n", stopstring ); 


string = "16118134932"; : 
printf( “string = %s\n", string ); 
/* Convert string using base 2, 4, and 8: */ 
for( base = 2; base <= 8; base *= 2 ) 
{ 
/* Convert the string: */ 
ul = strtoul( string, &stopstring, base ); 
printf( " strtol = %1ld (base %d)\n", ul, base ); 
printf( " Stopped scan at: %s\n", stopstring ); 


Output 


String = 3.1415926This stopped it 
strtod = 3.141593 
Stopped scan at: This stopped it 


String = -19110134932This stopped it 
strtol = -2147483647 
Stopped scan at: This stopped it 


string = 19110134932 
strtol = 45 (base 2) 
Stopped scan at: 34932 
strtol = 4423 (base 4) 
Stopped scan at: 4932 
strtol = 2134108 (base 8) 
Stopped scan at: 932 
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Description 


Remarks 


Return Value 


Compatibility 


Find the next token in a string. 
#include <string.h> Required only for function declarations 


char *strtok( char *string/, const char *string2 ); 


char far * far _fstrtok( char _far *string/, const char _far *string2 ); 


string] String containing token(s) 


string2 Set of delimiter characters 


The strtok function reads string/ as a series of zero or more tokens and string2 as the set 
of characters serving as delimiters of the tokens in string]. The tokens in string] may be 
separated by one or more of the delimiters from string2. 


The tokens can be broken out of string! by a series of calls to strtok. In the first call to 
strtok for string1, strtok searches for the first token in string/, skipping leading 
delimiters. A pointer to the first token is returned. To read the next token from string], call 
strtok with a NULL value for the string] argument. The NULL string] argument causes 
strtok to search for the next token in the previous token string. The set of delimiters may 
vary from call to call, so string2 can take any value. 


The _fstrtok function is a model-independent (large-model) form of the strtok function. 
The behavior and return value of _fstrtok are identical to those of the model-dependent 
function strtok, with the exception that the arguments and return value are far pointers. 


Note that calls to these functions will modify string/, since each time strtok is called it in- 
serts a null character (’\0’) after the token in string/. 


The first time strtok is called, it returns a pointer to the first token in string/. In later calls 
with the same token string, strtok returns a pointer to the next token in the string. A 
NULL pointer is returned when there are no more tokens. All tokens are null-terminated. 


strtok 
@ ANSI @ DOS 8 OS/ UNIX” Wf XENIX 
_fstrtok 
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779 strtok, _fstrtok 


See Also strcspn, strspn 


Example 


/* STRTOK.C: In this program, a loop uses strtok to print all the tokens 
* (separated by commas or blanks) in the string named “string”. 
a | 


#Hinclude <string.h> 
#Hinclude <stdio.h> 


char string[] = "A string\tof ,,tokens\nand some more tokens"; 
char sepsC] =" ,\t\n"; 
char *token;: 


void main() 


{ 
printf( "%s\n\nTokens:\n", string ); 


/* Establish string and get the first token: */ 
token = strtok( string, seps ); 
while( token != NULL ) 
{ 
/* While there are tokens in "string" */ 
printf( " %s\n", token ); 
/* Get next token: */ 
token = strtok( NULL, seps ); 


Output 


A string of ,,tokens 
and some more tokens 


Tokens: 
A 
string 
of 
tokens 
and 
some 
more 
tokens 
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Description Convert a string to uppercase. 
#include <string.h> Required only for function declarations 


char *strupr( char *string ); 


char _far* far _fstrupr( char _far *string ); 
string String to be capitalized 


Remarks These functions convert any lowercase letters in the string to uppercase. Other characters 
are not affected. 


The _fstrupr function is a model-independent (large-model) form of the strupr function. 
The behavior and return value of _fstrupr are identical to those of the model-dependent 
function strupr, with the exception that the argument and return value are far pointers. 


Return Value These functions return a pointer to the converted string. There is no error return. 
Compatibility O ANSI! @ DOS #8 OS/72 O UNIX OC XENIX 

See Also strlwr 

Example 


/* STRLWR.C: This program uses strlwr and strupr to create 
* uppercase and lowercase copies of a mixed-case string. 
xf: 


#Hinclude <string.h> 
#Hinclude <stdio.h> 


void main() 

{ 
char string[100] = "The String to End All Strings!"; 
char *copyl, *copy2; 


copyl = striwr( strdup( string ) ); 
copy2 = strupr( strdup( string ) ); 
printf( "Mixed: 4%s\n", string ); 
printf( “Lower: %s\n", copyl ); 
printf( "Upper: %s\n", copy2 ); 
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Output 


Mixed: The String to End All Strings! 
Lower: the string to end all strings! 
Upper: THE STRING TO END ALL STRINGS! 


strxfrm 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Transforms a string based on locale-specific information. 
#include <string.h> | Required only for function declarations 


size_t strxfrm( char *string/, const char *string2, size_t count ); 


string] String to which transformed version of string2 is returned 
string2 String to transform 


count Maximum number of characters to be placed in string] 


The strxfrm function transforms the string pointed to by string2 into a new form that is 
stored in string]. No more than count characters (including the null character) are trans- 
formed and placed into the resulting string. 


The transformation is made using the information in the locale-specific LC_COLLATE 
macro. 


After the transformation, a call to stremp with the two transformed strings will yield iden- 
tical results to a call to strcoll applied to the original two strings. 


The value of the following expression is the size of the array needed to hold the transfor- 
mation of the source string: 


1 + strxfrm( NULL,:string, @ ) 


Currently, the C libraries support the "C" locale only; thus strxfrm is equivalent to the 
following: 


strncpy( _stringl, _string2, _count ); 
return( strien( _string2 ) ); 


The strxfrm function returns the length of the transformed string, not counting the termi- 
nating null character. If the return value is greater than or equal to count, the contents of 
string] are unpredictable. 
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localecony, setlocale, strncmp 
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Description Swaps bytes. 
#include <stdlib.h> Required only for function declarations 


void swab( char *src, char *dest, int n ); 


STC Data to be copied and swapped 
dest Storage location for swapped data 
n Number of bytes to be copied and swapped 
Remarks The swab function copies 1 bytes from src, swaps each pair of adjacent bytes, and stores 


the result at dest. The integer 1 should be an even number to allow for swapping. The 
swab function is typically used to prepare binary data for transfer to a machine that uses a 
different byte order. 


Return Value None. 


Compatibility O ANS! @ DOS @ OS/2 WM UNIX & XENIX 


Example 


/* SWAB.C */ 
dHinclude <stdlibsh> 
#Hinclude <stdio.h> 


char from[] = "“BADCFEHGJILKNMPORQTSVUXWZY"; 
char to{] = PuaWe oigtots dusiie asia Ww Nas ane arnenenage ead me 


void main() 
{ 
printf( "Before:\t%s\n\t%s\n\n", from, to ); 
swab( from, to, sizeof( from ) ); 
printf( “After:\t%s\n\t%s\n\n", from, to ); 
} 


Output 


Before: BADCFEHGJILKNMPOROQTSVUXWZY 


After: BADCFEHGJILKNMPORQTSVUXWZY 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


system 
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Description 


Rematks 


Return Value . 


Executes a command. 


#include <process.h> Required only for function declarations 


#include <stdlib.h> Use STDLIB.H for ANSI compatibility 
int system( const char *command ); 
command Command to be executed 


The system function passes command to the command interpreter, which executes the 
string as an operating-system command. The system function refers to the COMSPEC and 
PATH environment variables that locate the command-interpreter file (the file named 
COMMAND.COM in DOS or CMD.EXE in OS/2). If command is a pointer to an empty 
string, the function simply checks to see whether or not the command interpreter exists. 


If command is NULL and the command interpreter is found, the function returns a nonzero 
value. If the command interpreter is not found, it returns the value 0 and sets errno to 
ENOENT. If command is not NULL, the system function returns the value 0 if the com- 
mand interpreter is successfully started. Under OS/2, the system function returns the exit 
status from the command interpreter. | 


A return value of —1 indicates an error, and errno is set to one of the following values: 


Value Meaning 


E2BIG In DOS, the argument list exceeds 128 bytes, or the space re- 
quired for the environment information exceeds 32K. In OS/2, 
the combined argument list and space required for environ- 
ment information exceed 32K. 


ENOENT The command interpreter cannot be found. 

ENOEXEC The command-interpreter file has an invalid format and is not 
executable. 

ENOMEM Not enough memory is available to execute the command; or 


the available memory has been corrupted; or an invalid block 
exists, indicating that the process making the call was not allo- 
cated properly. 


785 system 


Compatibility MANS! M@ DOS MH OS/ WM UNIX WI XENIX 


See Also exec functions, exit, exit, spawn functions 


Example 


/* SYSTEM.C: This program uses system to TYPE its source file. */ 
#Hinclude <process.h> 

void main() 

system( "type system.c" ); 

Output 

/* SYSTEM.C: This program uses system to TYPE its source file. */ 
#Hinclude <process.h> | 


void main() 
{ 


} 


system( “type system.c" ); 


tan Functions 786 


Description Calculate the tangent (tan and tanl) and hyperbolic tangent (tanh and tanhl). 
#include <math.h> 


double tan( double x ); 

double tanh( double x ); 

long double tanl( long double x ); 
long double tanhl( long double x ); 


x Angle in radians 


Remarks The tan functions return the tangent or hyperbolic tangent of their arguments. The list 
below describes the differences between the various tangent functions: 


Function Description 

tan Calculates tangent of x 

tanh Calculates hyperbolic tangent of x 

tanl Calculates tangent of x (80-bit version) 

tanhl Calculates hyperbolic tangent of x (80-bit version) 


The tanl and tanhl functions are the 80-bit counterparts and use an 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long double 
functions for more details on this data type. 


Return Value The tan function returns the tangent of x. If x is large, a partial loss of significance in the 
result may occur; in this case, tan sets errno to ERANGE and generates a PLOSS error. If 
x is so large that significance is totally lost, tan prints a TLOSS error message to stderr, 
sets errno to ERANGE, and returns 0. 


There is no error return for tanh. 

Compatibility tan, tanh 
@ ANS| #& DOS HF OS/2 HF UNIX 8 XENIX 
tanl, tanhl 
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See Also acos functions, asin functions, atan functions, cos functions, sin functions 


Example 


/* TAN.C: This program displays the tangent of pi / 4 and the hyperbolic 
* tangent of the result. 
ey 


#Hinclude <math.h> 
dHinclude <stdio.h> 


void main() 
{ F 
double pi = 3.1415926535; 
double x, y; 


x = tan( pi / 4 ); 

y = tanh( x ); 

printf( “tan( 2f ) = Zf\n", x, y ); 
printf( “tanh( 2f ) = 4f\n", y, x ); 


Output 


tan( 1.@8@008 ) = 9.761594 
tanh( 9.761594 ) = 1.980000 


tell 
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ne 


Remarks 


Return Value - 


Compatibility 


See Also 


Example 
/* TELL.C: 


“Description — 


Gets the position of the file pointer. 

#include <io.h> Required only for function declarations 
long tell( int handle ); 

handle | Handle referring to open file 


The tell function gets the current position of the file pointer (if any) associated with the 
handle argument. The position is expressed as the number of bytes from the beginning of 
the file. | 


- A return value of —1L indicates an error, and errno is set to EBADF to indicate an invalid 


file-handle argument. On devices incapable of seeking, the return value is undefined. 


O ANSi #@ DOS # OS/2 OF UNIX OC XENIX 
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This program uses tell to tell the file pointer position 


* after a file read. 


*/ 


#Hinclude <io.h> 


#Hinclude <stdio.h> 
dHinclude <fcnt1l.h> 


void main() | 


{ 


int fh; 


— long position; 
char buffer[520]; 


 4#( (fh = open( "tell.c", O_RDONLY )) != -1 ) 


( 


if( tead( fh, buffer, 500 )>@ ) 
printf( "Current file position is: 4d\n", tell( fh ) ); 


789 tell 
close( fh ); 
} 


Output 


Current file position is: 425 
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Description 


Remarks 


Create temporary file names. 
#include <stdio.h> 


char *tempnam( char *dir, char *prefix ); 


char *tmpnam( char *string ); 


string Pointer to temporary name 
dir Target directory to be used if TMP not defined 
prefix File-name prefix 


The tmpnam function generates a temporary file name that can be used to open a tem- 
porary file without overwriting an existing file. This name is stored in string. If string is 
NULL, then tmpnam leaves the result in an internal static buffer. Thus, any subsequent 
calls destroy this value. If string is not NULL, it is assumed to point to an array of at least 
L_tmpnam bytes (the value of L_tmpnam is defined in STDIO.H). The function will 
generate unique file names for up to TMP_MAX calls. 


The character string that tmpnam creates consists of the path prefix, defined by the entry 
P_tmpdir in the file STDIO.H, followed by a sequence consisting of the digit characters 
’0’ through ’9’; the numerical value of this string can range from 1 to 65,535. Changing 
the definitions of L_tmpnam or P_tmpdir in STDIO.H does not change the operation of 
tmpnam. 


The tempnam function allows the program to create a temporary file name for use in 
another directory. This file name will be different from that of any existing file. The 

prefix argument is the prefix to the file name. The tempnam function uses malloc to allo- 
cate space for the file name; the program is responsible for freeing this space when it is no 
longer needed. The tempnam function looks for the file with the given name in the follow- 
ing directories, listed in order of precedence: 


Directory Used Conditions 

Directory specified by TMP TMP environment variable is set, and 
directory specified by TMP exists. 

dir argument to tempnam TMP environment variable is not set, or 
directory specified by TMP does not exist. 

P_tmpdir in STDIO.H The dir argument is NULL, or dir is name 


of nonexistent directory. 
Current working directory P_tmpdir does not exist. 
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Return Value 


Compatibility 


See Also 


Example 


_If the search through the locations listed above fails, tempnam returns the value NULL. 


The tmpnam and tempnam functions both return a pointer to the name generated, unless 
it is impossible to create this name or the name is not unique. If the name cannot be 
created or if a file with that name already exists, tmpnam and tempnam return the value 
NULL. 


tmpnam 
M@ ANS! @ DOS M OS/2 WM UNIX @ XENIX 
tempnam 


O ANS! #@ DOS H OS/2 UNIX Mf XENIX 


tmpfile 


/* TEMPNAM.C: This program uses tmpnam to create a unique file name in 
* the current working directory, then uses tempnam to create a unique 
* file name with a prefix of stq. 


so 


#Hinclude <stdio.h> 


void main() 


{ 


char *namel, *name2; 


/* Create a temporary file name for the current working directory: */ 
if( ( namel = tmpnam( NULL ) ) != NULL ) 
printf( "%’s is safe to use as a temporary file.\n", namel ); 


else 


printf( "Cannot create a unique file name\n" ); 


/* Create a temporary file name in temporary directory with the 
* prefix “stq". The actual destination directory may vary depending 
* on the state of the TMP environment variable and the global variable 


* P_tmpdir. 


i | 


if( ( name2 = tempnam( "c:\\tmp", "stq"™ ) ) != NULL ) 
printf( "%s is safe to use as a temporary file.\n", name2 ); 


else 


printf( "Cannot create a unique file name\n" ); 
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Output 


\2 is safe to use as a temporary file. 
C:\TMP\stq2 is safe to use as a temporary file. 


793 time 


Description Gets the system time. 
#include <time.h> Required only for function declarations 
time_t time( time_t *timer ); 
timer Storage location for time 


Remarks The time function returns the number of seconds elapsed since 00:00:00 Greenwich mean 
time (GMT), January 1, 1970, according to the system clock. The system time is adjusted 
according to the timezone system variable, which is explained in the tzset reference 
section. 


The return value is stored in the location given by timer. This parameter may be NULL, in 
which case the return value is not stored. 
Return Value The time function returns the time in elapsed seconds. There is no error return. 


Compatibility MANS! @ DOS M@ OS/2 WM UNIX MB XENIX 


See Also asctime, ftime, gmtime, localtime, tzset, utime 


Example 


/* CTIME.C: This program gets the current time in time_t form, then uses 
* ctime to display the time in string form. 
sail) 


dHinclude <time.h> 
dHinclude <stdio.h> 


void main() 
{ 
time_t Itime; 
time( &ltime ); 
printf( "The time is %s\n", ctime( &ltime ) ); 
} 
Output 


The time is Thu Jun 15 16:98:18 1989 
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Description Creates a temporary file. 
#include <stdio.h> 
FILE *tmpfile( void ); 


Remarks The tmpfile function creates a temporary file and returns a pointer to that stream. If the 
file cannot be opened, tmpfile returns a NULL pointer. 


This temporary file is automatically deleted when the file is closed, when the program ter- 
minates normally, or when rmtmp is called, assuming that the current working directory 
does not change. The temporary file is opened in w+b (binary read/write) mode. 


Return Value If successful, the tmpfile function returns a stream pointer. Otherwise, it returns a NULL 
pointer. 


Compatibility MANS! DOS M@ OS/ WM UNIX @ XENIX 


See Also rmtmp, tempnam, tmpnam 


Example 


/* TMPFILE.C: This program uses tmpfile to create a temporary file, 
* then deletes this file with rmtmp. 
*/ 


dFinclude <stdio.h> 


void main() 

( 
FILE *stream; 
char tempstring[] = "String to be written"; 
int i; 


/* Create temporary files. */ 
for( i = 1; i <= 10; i++ ) 
{ 
if( (stream = tmpfile()) == NULL ) 
perror( "Could not open new temporary file\n" ); 
else 
a printf( "Temporary file %d was created\n", i ); 
} 


/* Remove temporary files. */ 
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printf ( "“%d temporary files deleted\n", rmtmp() ); 


Output 


was created 
was created 
was created 
was created 
was created 
was created 
was created 


Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 8 was created 
Temporary file 9 was created 
Temporary file 10 was created 
18 temporary files deleted 
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Description 


Remarks 


Convert characters. 
#include <ctype.h> 


int toascii( int c ); 
int tolower( int c ); 
int _tolower( int c ); 
int toupper( int c ); 


int _toupper( int c ); 
Cc Character to be converted 


The toascii, tolower, tolower, toupper, and _toupper routines convert a single charac- 
ter, as described below: 


Function Description 

toascii Converts c to ASCII character 
tolower Converts c to lowercase if appropriate 
_tolower Converts c to lowercase 

toupper Converts c to uppercase if appropriate 
_toupper Converts c to uppercase 


The toascii routine sets all but the low-order 7 bits of c to 0, so that the converted value 
represents a character in the ASCII character set. If c already represents an ASCII charac- 
ter, c is unchanged. 


The tolower and _tolower routines convert c to lowercase if c represents an uppercase let- 
ter. Otherwise, c is unchanged. The _tolower routine is a version of tolower to be used 
only when c is known to be uppercase. The result of _tolower is undefined if c is not an 
uppercase letter. 


The toupper and _toupper routines convert c to uppercase if c represents a lowercase let- 
ter. Otherwise, c is unchanged. The _toupper routine is a version of toupper to be used 
only when c is known to be lowercase. The result of _toupper is undefined if c is not a 
lowercase letter. 
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Note that these routines are implemented both as functions and as macros. To conform 
with the ANSI specification, the tolower and toupper routines are also implemented as 
functions. The function versions can be used by removing the macro definitions through 
#undef directives or by not including CTYPE.H. Function declarations of tolower and 
toupper are given in STDLIB.H. 


If the -Za compile option is used, the macro form of toupper or tolower is not used be- 
cause it evaluates its argument more than once. Since the arguments are evaluated more 
than once, arguments with side effects would produce potentially bad results. 


Return Value The toascii, éclower _tolower, toupper, and _toupper routines return the converted char- 
acter c. There is no error return. 


Compatibility toascii, _tolower, toupper 


O ANS| @ DOS # OS/2 Mf UNIX” MB XENIX 
tolower, toupper 


MANS! @ DOS @ OS/2 W@W UNIX @) XENIX 


See Also is functions 


Example 


/* TOUPPER.C: This program uses toupper and tolower to analyze all 

* characters between @x®@ and @x7F. It also applies _toupper and _tolower 
* to any code in this range for which these functions make sense. 

*/ 


#Hinclude <conio.h> 
#Hinclude <ctype.h> 
#Finclude <string.h> 


char msgl] = "Some of THESE letters are Capitals\r\n"; 
char *p; 


void main() 
{ 
cputs( msg ); 
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/* Reverse case of message. */ 
for( p = msg; p < msg + strien( msg ); ptt ) 
{ 
if( islower( *p ) ) 
putch( _toupper( *p ) ); 
else if( isupper( *p ) ) 
putch( _tolower( *p ) ); 
else 
putch( *p ); 


Output 


Some of THESE letters are Capitals 
SOME OF these LETTERS ARE cAPITALS 
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Description Sets time environment variables. 
#include <time.h> Required only for function declarations 


void tzset( void ); 


int daylight; Global variables set by function 
long timezone; 
char *tzname[2] 


Remarks The tzset function uses the current setting of the environment variable TZ to assign values 
to three global variables: daylight, timezone, and tzname. These variables are used by the 
ftime and localtime functions to make corrections from Greenwich mean time (GMT) to 
local time, and by time to compute GMT from system time. 


The value of the environment variable TZ must be a three-letter time-zone name, such as 
PST, followed by an optionally signed number giving the difference in hours between 
GMT and local time. The number may be followed by a three-letter daylight-saving-time 
(DST) zone, such as PDT. For example, “PST8PDT” represents a valid TZ value for the 
Pacific time zone. If DST is never in effect, as is the case in certain states and localities, 
TZ should be set without a DST zone. 


If the TZ value is not currently set, the default is PST8PDT, which corresponds to the 
Pacific time zone. 


Based on the TZ environment variable value, the following values are assigned to the vari- 
ables daylight, timezone, and tzname when tzset is called: 


Variable Value 

daylight Nonzero value if a daylight-saving-time zone is specified in 
the TZ setting; otherwise, 0 

timezone Difference in seconds between GMT and local time 

tzname(0] String value of the three-letter time-zone name from the TZ 
setting 

tzname[1] String value of the daylight-saving-time zone, or an empty 

string if the daylight-saving-time zone is omitted from the TZ 

setting 


The default for daylight is 1; for timezone, 28,800; for tzname[0], PST; and for 
tzname[1], PDT. This corresponds to “PST8PDT.” 


If the DST zone is omitted from the TZ settings, the daylight variable will be 0 and the 
ftime, gmtime, and localtime functions will return 0 for their DST flags. 


tzset 800 


Return Value None. 

Compatibility O ANS| @ DOS  OS/2 Mf UNIX. M& XENIX 
See Also asctime, ftime, gmtime, localtime, time 

Example 


/* TZSET.C: This program first sets up the time zone by placing the variable 
* named TZ=EST5 in the environment table. It then uses tzset to set the 

* global variables named daylight, timezone, and tzname. 

*/ 


#Hinclude <time.h> 
dHinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main() 
{ 


if( putenv( "TZ=EST5EDT" ) == -1 ) 
“{ 

printf( "Unable to set TZ\n" ); 
exit( 1); 

} “ 

else 

{ 
tzset(); 


printf( "daylight = @d\n", daylight ); 
printf( “timezone = 41d\n", timezone ); 
printf( "tzname[@] = %s\n", tzname[@] ); 


Output 


daylight = 1 
timezone = 18000 
tzname[Q] = EST 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


ultoa 


Converts an unsigned long integer to a string. 
#include <stdlib.h> Required only for function declarations 


char *ultoa( unsigned long value, char *string, int radix ); 


value Number to be converted 
String String result 
radix Base of value 


The ultoa function converts value to a null-terminated character string and stores the result 
(up to 33 bytes) in string. No overflow checking is performed. The radix argument speci- 
fies the base of value; it must be in the range 2-36. 


The ultoa function returns a pointer to string. There is no error return. 
O ANS! M@ DOS WM OS/2 CO UNIX O XENIX 
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/* ITOA.C: This program converts integers of various sizes to strings 
* in various radixes. 


*/ 


#Hinclude <stdlib.h> 
dHinclude <stdio.h> 


void main() 
{ 


char buffer(20]; 

int i = 3445; 

long 1 = -344115L; 

unsigned long ul = 123456789QUL; 


itoa( i, buffer, 10 ); 

printf( “String of integer 4d (radix 10): %s\n", i, buffer ); 
jtoa( i, buffer, 16 ); 

printf( “String of integer %d (radix 16): O@x%s\n", i, buffer ); 
itoa( i, buffer, 2 ); ; 

printf( “String of integer %d (radix 2): %s\n", i, buffer ); 
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ltoa( 1, buffer, 16 ); 
printf( “String of long int 41d (radix 16): Ox%s\n", 1, buffer ); 


ultoa( ul, buffer, 16 ); 
printf( “String of unsigned long %lu (radix 16): Ox%s\n", ul, buffer ); 


Output 


String of integer 3445 (radix 10): 3445 

String of integer 3445 (radix 16): @xd75 

String of integer 3445 (radix 2): 1101011191901 

String of long int -344115 (radix 16): Oxfffabfcd 

String of unsigned long 1234567898 (radix 16): 0x4996@2d2 


803 umask 


Description Sets the default file-permission mask. 
#include <sys\types.h> 
#include <sys\stat.h> 
#include <io.h> Required only for function declarations 


int umask( int pmode ); 
pmode Default permission setting 


Remarks The umask function sets the file-permission mask of the current process to the mode 
specified by pmode. The file-permission mask is used to modify the permission setting of 
new files created by creat, open, or sopen. If a bit in the mask is 1, the corresponding bit 
in the file’s requested permission value is set to 0 (disallowed). If a bit in the mask is 0, the 
corresponding bit is left unchanged. The permission setting for a new file is not set until 
the file is closed for the first time. 


The argument pmode is a constant expression containing one or both of the manifest con- 
stants S IREAD and S_IWRITE, defined in SYS\STAT.H. When both constants are given, 
they are joined with the bitwise-OR operator ( | ). The meaning of the pmode argument is 


as follows: 

Value Meaning 

S IREAD Reading not allowed (file is write-only) 
S_IWRITE Writing not allowed (file is read-only) 


For example, if the write bit is set in the mask, any new files will be read-only. 
Note that under DOS and OS/2, all files are readable—it is not possible to give write-only 
permission. Therefore, setting the read bit with umask has no effect on the file’s modes. 


Return Value The umask function returns the previous value of pmode. There is no error return. 


Compatibility O ANS! @ DOS M@ OS/2 W@W UNIX MT XENIX 
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See Also chmod, creat, mkdir, open 


Example 


/* UMASK.C: This program uses umask to set the file-permission mask so 
* that all future files will be created as read-only files. It also 

* displays the old mask. 

x 


#Hinclude <sys\types.h> 
#include <sys\stat.h> 
#Hinclude <io.h> 
#Hinclude <stdio.h> 


void main() 
{ 
int oldmask; 
/* Create read-only files: */ 


oldmask = umask( S_IWRITE ); 
printf( "Oldmask = Ox%.4x\n", oldmask ); 


Output 


Oldmask = Qx00Q2 
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Description 


Remarks 


Return Value 


Compatibility 
See Also 


Example 


ungete 


Pushes a character back onto the stream. 
#include <stdio.h> 
int ungetc( int c, FILE *stream ); 


c Character to be pushed 


stream Pointer to FILE structure 


The ungete function pushes the character c back onto stream and clears the end-of-file in- 
dicator. The stream must be open for reading. A subsequent read operation on the stream 
starts with c. An attempt to push EOF onto the stream using ungetc is ignored. The 
ungetc function returns an error value if nothing has yet been read from stream or if c can- 
not be pushed back. 


Characters placed on the stream by ungetc may be erased if fflush, fseek, fsetpos, or 
rewind is called before the character is read from the stream. The file-position indicator 
will have the same value it had before the characters were pushed back. On a successful 
ungetc call against a text stream, the file-position indicator is unspecified until all the 
pushed-back characters are read or discarded. On each successful ungete call against a bi- 
nary stream, the file-position indicator is stepped down; if its value was 0 before a call, the 
value is undefined after the call. 


Results are unpredictable if the ungetc function is called twice without a read operation be- 
tween the two calls. After a call to the fscanf function, a call to ungetc may fail unless 
another read operation (such as the'getc function) has been performed. This is because the 
fscanf function itself calls the ungetc function. 


The ungetc function returns the character argument c. The return value EOF indicates a 
failure to push back the specified character. 


MANS! M@ DOS @ OS/2 MW UNIX’ Mf XENIX 


getc, getchar, putc, putchar 


/* UNGETC.C: This program first converts a character representation of an 
* unsigned integer to an integer. If the program encounters a character 
* that is not a digit, the program uses ungetc to replace it in the stream. 


bas 


ungetec - 806 


dHinclude <stdio.h> 
#Hinclude <ctype.h> 


void main() 
{ 
int ch; 
int result = @; 


printf( “Enter an integer: " ); 


/* Read in and convert number: */ 
while( ((ch = getchar()) != EOF) && isdigit( ch ) ) 


result = result * 18+ ch - 'Q'; /* Use digit. */ 
if( ch != EOF ) 
ungetc( ch, stdin ); /* Put non-digit back. */ 


printf( "Number = %d\nNext character in stream = ‘%c'\n", 
result, getchar() ); 


Output 


Enter an integer: 521la 
Number = 521 
Next character in stream = ‘a' 
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Description 


Remarks 


Return Value 


Compaiibility 


See Also 


Example 


ungeich 


Pushes back the last character read from the console. 

#include <conio.h> Required only for function declarations 
int ungetch( int c ); 

Cc Character to be pushed 


The ungetch function pushes the character c back to the console, causing c to be the next 
character read by getch or getche. The ungetch function fails if it is called more than once 
before the next read. The c argument may not be EOF. 


‘ 


The ungetch function returns the character c if it is successful. A return value of EOF indi- 
cates an error. 
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/* UNGETCH.C: In this program, a white-space delimited token is read 
* from the keyboard. When the program encounters a delimiter, 
* it uses ungetch to replace the character in the keyboard buffer. 


a 


#Hinclude <conio.h> 
#Hinclude <ctype.h> 
fHinclude <stdio.h> 


void main() 


{ 


char buffer[{100]; 
int count = Q; 


int ch; 
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ch = getche(); 


while( isspace( ch ) ) /* Skip preceding white space. */ 
ch = getche(); 
while( count < 99 ) /* Gather token. */ 
{ 
if( isspace( ch ) ) /* End of token. */ 
break; 


buffer{count++] = ch; 

ch = getche(); 
} 
ungetch( ch ); /* Put back delimiter. */ 
buffer[count] = '\Q'; /* Null terminate the token. */ 
printf( "\ntoken = %s\n", buffer ); 


Output 


White 
token = White 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


unlink 


Deletes a file. 
#include <io.h> Required only for function declarations 
#include <stdio.h> Use either IO.H or STDIO.H 


int unlink( const char *filename ); 
filename Name of file to remove 
The unlink function deletes the file specified by filename. 


If successful, unlink returns 0; otherwise, it returns —1 and sets errno to one of the follow- 
ing constants: 


Value Meaning 
EACCES ’ Path name specifies a read-only file 
ENOENT File or path name not found, or path name specified a directory 
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close, remove 


/* UNLINK.C: This program uses unlink to delete UNLINK.OBJ. */ 


fHinclude <stdio.h> 


void main() 


{ 


if( unlink( “unlink.obj" ) == -1 ) 
perror( “Could not delete 'UNLINK.OBJ'" ); 


else 


printf( "Deleted 'UNLINK.OBJ'\n" ); 


Output 


Deleted ‘UNLINK.OBJ' 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


Frees memory used by fonts. 
#include <graph.h> 
void far _unregisterfonts( void ); 


The _unregisterfonts function frees memory previously allocated and used by the 
_registerfonts function. The _unregisterfonts function removes the header information 
for all fonts and unloads the currently selected font data from memory. 


Any attempt to use the _setfont or _outgtext function after calling _unregisterfonts re- 
sults in an error. 

None. 
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_getfontinfo, _getgtextextent, outgtext, registerfonts, _setfont 


See the example for _outgtext. 


811 utime 
Description Sets the file modification time. 

#include <sys\types.h> 

#include <sys\utime.h> 

int utime( char *filename, struct utimbuf *times ); 

filename File name 

times Pointer to stored time values 
Remarks The utime function sets the modification time for the file specified by filename. The 


Return Value 


Compatibility 
See Also 


Example 


process must have write access to the file; otherwise, the time cannot be changed. 


Although the utimbuf structure contains a field for access time, only the modification time 
is set under DOS and OS/2 . If times is a NULL pointer, the modification time is set to the 
current time. Otherwise, times must point to a structure of type utimbuf, defined in 
SYS\UTIME.H. The modification time is set from the modtime field in this structure. 


The utime function returns the value 0 if the file-modification time was changed. A return 
value of —1 indicates an error, and errno is set to one of the following values: 


Value Meaning 

EACCES Path name specifies directory or read-only file 

EINVAL Invalid argument; the times argument is invalid 

EMFILE Too many open files (the file must be opened to change its 


modification time) 


ENOENT File or path name not found 
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asctime, ctime, fstat, ftime, gmtime, localtime, stat, time 


/* UTIME.C: This program uses utime to set the file-modification time to 
* the current time. 


*/ 


utime 812 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <sys\types.h> 
#Finclude <sys\utime.h> 


void main() 


/* Show file time before and after. */ 
system( “dir utime.c" ); 
if( utime( “utime.c", NULL ) == -1 ) 
perror( “utime failed\n" ); 
else 
printf( "File time modified\n" ); 
system( "dir utime.c" ); 


Output 


The volume label in drive C is OS2. 
Directory of C:\LIBREF 


UTIME C 397 6-20-89 2:1llp 
1 File(s) 12974880 bytes free 
File time modified 


The volume label in drive C is 0S2. 
Directory of C:\LIBREF 


UTIME C 397 6-29-89 2:12p 
1 File(s) 12974080 bytes free 
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va_arg, va_end, va_start 


Description 


Remarks 


Access variable-argument lists. 


#include <stdarg.h> Required for ANSI compatibility 
#include <varargs.h> Required for UNIX V compatibility 


#include <stdio.h> 


type va_arg( va_list arg _ptr, type ); 
void va_end( va_list arg _ptr ); 
void va_start( va_list arg_ptr ); UNIX version 


void va_start( va_list arg_ptr, prev_param ); ANSI 


arg ptr Pointer to list of arguments 
prev_param Parameter preceding first optional argument (ANSI only) 


type Type of argument to be retrieved 


The va_arg, va_end, and va_start macros provide a portable way to access the arguments 
to a function when the function takes a variable number of arguments. Two versions of the 
macros are available: the macros defined in STDARG.H conform to the proposed ANSI C 
standard, and the macros defined in VARARGS.H are compatible with the UNIX System 


_V definition. The macros are listed below: 


Macro” Description 

va_alist Name of parameter to called function (UNIX version only) 
' va_arg Macro to retrieve current argument 

va_dcl Declaration of va_alist (UNIX version only) 

va_end Macro to reset arg_ptr 

va_list The typedef for the pointer to list of arguments 

va_start Macro to set arg_ptr to beginning of list of optional argu- 

ments (UNIX version only) 


Both versions of the macros assume that the function takes a fixed number of required ar- 
guments, followed by a variable number of optional arguments. The required arguments 
are declared as ordinary parameters to the function and can be accessed through the param- 
eter names. The optional arguments are accessed through the macros in STDARG.H or 
VARARGS.H, which set a pointer to the first optional argument in the argument list, 
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retrieve arguments from the list, and reset the pointer when argument processing is 
completed. 


The proposed ANSI C standard macros, defined in STDARG.H, are ite as follows: 


1. 


All required arguments to the function are declared as parameters in the usual way. The 
va_dcl macro is not used with the STDARG.H macros. 


. The va_start macro sets arg_pir to the first optional argument in the list of arguments 


passed to the function. The argument arg_ptr must have va_list type. The argument 
prev_param is the name of the required parameter immediately preceding the first 
optional argument in the argument list. If prev_param is declared with the register 
storage class, the macro’s behavior is undefined. The va_start macro must be used 
before va_arg is used for the first time. 


. The va_arg macro does the following: 


m@ Retrieves a value of type from the location given by arg_ptr 


@ Increments arg_ptr to point to the next argument in the list, using the size of type to 


determine where the next argument starts 


The va_arg macro can be used any number of times within the function to retrieve ar- 
guments from the list. 


4. After all arguments have been retrieved, va_end resets the pointer to NULL. 


The UNIX System V macros, defined in VARARGS.H, operate in a slightly different man- 
ner, as follows: 


. Any required arguments to the function can be declared as parameters in the usual way. 


. The last (or only) parameter to the function represents the list of optional arguments. 


This parameter must be named va_alist (not to be confused with va_list, which is de- 
fined as the type of va_alist). 


. The va_dcl macro appears after the function definition and before the opening left 


brace of the function. This macro is defined as a complete declaration of the va_alist 
parameter, including the terminating semicolon; therefore, no semicolon should 1 follow 
va_del. 


‘ Within the function, the va_start macro sets arg_ptr to the beginning of the list of op- 


tional arguments passed to the function. The va_start macro must be used before 
va_arg is used for the first time. The argument arg_ptr must have va_list type. 


. The va_arg macro does the following: 


m@ Retrieves a value of type from the location given by arg_ptr 


m Increments arg ptr to point to the next argument in the list, using the size of type to 
determine where the next argument starts 
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The va_arg macro can be used any number of times within the function to retrieve the 
arguments from the list. 


6. After all arguments have been retrieved, va_end resets the pointer to NULL. 


Return Value The va are macro returns the current argument; va_start and va_end do not return values. 
Compatibility MANS! @ DOS ® OS/2 Mf UNIX. Mf XENIX 

See Also vfprintf, vprintf, vsprintf 

Example 


/* VA.C: The program below illustrates passing a variable number of arguments 
* using the following macros: 


* va_start Va_arg va_end 

* va_list va_decl (UNIX only) 

* / 
fHinclude <stdio.h> 
dtdefine ANSI /* Comment out for UNIX version */ 
dHifdef ANSI /* ANSI compatible version */ 


#Hinclude <stdarg.h> 

int average( int first, ... ); 

ffelse /* UNIX compatible version */ 
#Hinclude <varargs.h> 

int average( va_list ); 

fHendif 


void main() 
{ - 
/* Call with 3 integers (-1 is used as terminator). */ 
printf( “Average is: 4d\n", average( 2, 3, 4, -1 ) ); 


/* Call with 4 integers. */ 
printf( “Average is: 4d\n", average( 5, 7, 9, 11, -1 ) ); 


/* Call with just -1 terminator. */ 
printf( "Average is: %d\n", average( -1 ) ); 
} 


/* Returns the average of a variable list of integers. */ 
#Hifdef ANSI /* ANSI compatible version */ 
int average( int first, ... ) 
{ 

int count = @, sum = Q, i = first; 

va_list marker; 
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} 


va_start( marker, first ); /* Initialize variable arguments. */ 
while( i != -1 ) 
{ 

sum += 7; 

count++; 

ij = va_arg( marker, int); 
} : 
va_end( marker ); /* Reset variable arguments. */ 
return( sum ? (sum / count) : @ ); 


f#telse /* UNIX compatible version must use old-style definition. */ 


int average( va_alist ) 
va_dcl 


{ 


} 


int i, count, sum; 
va_list marker; 


va_start( marker ); /* Initialize variable arguments. */ 

for( sum = count = 0; (i = va_arg( marker, int)) != -1; count++ ) 
sum += 7; 

va_end( marker ); /* Reset variable arguments. */ 


return( sum ? (sum / count) : @ ); 


dtendif 


Output 


Average is: 3 
Average is: 8 
Average is: Q 
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vfprintf, vprintf, vsprintf 


Description 


Remarks — 


Return Value 


Compatibility 


Write formatted output using a pointer to a list of arguments. 


#include <stdio.h> 
#include <varargs.h> Required for compatibility with UNIX System V 
#include <stdarg.h> Required for compatibility with the ANSI C standard 


int vfprintf( FILE *stream, const char *format, va_list argptr ); 
int vprintf( const char *format, va_list argptr ); 


int vsprintf( char *buffer, const char *format, va_list argptr ); 


stream Pointer to FILE structure 
format Format control 

argptr Pointer to list of arguments 
buffer Storage location for output 


The vfprintf, vprintf, and vsprintf functions format data and output data to the file 
specified by stream, to standard output, and to the memory pointed to by buffer, respective- 
ly. These functions are similar to their counterparts fprintf, printf, and sprintf, but each 
accepts a pointer to a list of arguments instead of an argument list. 


The format argument has the same form and function as the format argument for the Pee 
function; see printf for a description of format. 


The argptr parameter has type va_list, which is defined in the include files VARARGS.H 
and STDARG.H. The argptr parameter points to a list of arguments that are converted and 
output according to the corresponding format specifications in the format. 


The return value for vprintf and vsprintf is the number of characters written, not counting 
the terminating null character. If successful, the vfprintf return value is the number of 
characters written. If an output error occurs, it is a negative value. 
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See Also fprintf, printf, sprintf, va_arg, va_end, va_start 
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/* VPRINTF.C shows how to use vprintf functions to write new versions 
* of printf. The vsprintf function is used in the example. 
i 


#Hinclude <stdio.h> 
#Hinclude <graph.h> 
#Hinclude <string.h> 
#Hinclude <stdarg.h> 
#Hinclude <malloc.h> 


int wprintf( short row, short col, short clr, long bclr, char *fmt, ... ); 


void main() 
{ 
short fgd 
long bgd 


Q; 
OL; 


_clearscreen( _GCLEARSCREEN ); 
_outtext( "Color text example:\n\n" ); 


/* Loop through 8 background colors. */ 
for( bgd = OL; bad < 8; bgd++ ) 
{ 
wprintf( (int)bgd + 3, 1, 7, bgd, "Back: %d Fore:", bgd ); 


/* Loop through 16 foreground colors. */ 
for( fad = 0; fgd < 16; fgd++ ) 
wprintf( -1, -1, fod, -1L, “ %2d ", fad ); 


/* Full-screen window version of printf that takes row, column, textcolor, 
* and background color as its first arguments, followed by normal printf 
* format strings (except that \t is not handled). You can specify -1 for 
* any of the first arguments to use the current value. The function returns 
* the number of characters printed, or a negative number for errors. 

*] 

int wprintf( short row, short col, short clr, long belr, char *fmt, ... ) 

{ 
struct rccoord tmppos; 
short ret, size; 
va_list marker; 
char *buffer; 
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/* It's probably safe to use a buffer length of 512 bytes or five times 
* the length of the format string. 
*/] 
size = strien( fmt ); 
size = (size > 512) ? 512 : size * 5; 
if( (buffer = (char *)malloc( size )) == NULL ) 
return -1; 


/* Set text position. */ 
tmppos = _gettextposition(); 
if( row <1 ) 

row = tmppos.row; 
if( col <1) 

col = tmppos.col; 
_settextposition( row, col ); 


/* Set foreground and background colors. */ 
if( clr >= @ ) 

_settextcolor( clr ); 
if( belr >= @ ) 

_setbkcolor( belr ); 


/* Write text to a string and output the string. */ 
va_start( marker, fmt ); 

ret = vsprintf( buffer, fmt, marker ); 

va_end( marker ); 

_outtext( buffer ); 

free( buffer ); 

return ret; 
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Description Suspends the calling process. 
#include <process.h> 
int wait( int *termstat ); 
termstat Termination-status word and return code for terminated child 
process 
Remarks The wait function suspends the calling process until any of the caller’s immediate child 


processes terminate. If all of the caller’s children have terminated before it calls the wait 
function, the function returns immediately. 


If not NULL, termstat points to a buffer containing a termination-status word and return 
code for the child process. The status word indicates whether or not the child process 
ended normally by calling the OS/2 DosExit function. Supply NULL if you do not need 
the child’s termination-status word. 


If the child process did terminate normally, the low-order and high-order bytes of the 
termination-status word are as follows: 


Byte Contents 
Low order 0 
High order Low-order byte of the result code passed by the child process 


to DosExit. The DosExit function is called if the child 
process called exit or _ exit, if it returned from main, or if it 
reached the end of main. The low-order byte of the result 
code is either the low-order byte of the argument to _ exit or 
exit, the low-order byte of the return value from main, or a 
random value if the child process reached the end of main. 


Note that the OS/2 DosExit function allows programs to return a 16-bit result code. How- 
ever, the wait and cwait functions will return only the low-order byte of that result code. 
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wait 


Return Value 


Compatibility 
See Also 


Example 


If the child process terminated for any other reason, the high-order and low-order bytes of 
the termination-status word are as follows: 


Byte Contents 
Low order Termination code from DosWait: 
Code Meaning 
1 Hard-error abort 
2 Trap operation 
3 SIGTERM signal not 
intercepted 
High order 0 


If wait returns after normal termination of a child process, it returns the child’s process ID. 


If wait returns after abnormal termination of a child process, it returns the number —1 and 
sets errno to EINTR. 


Otherwise, wait returns —1 immediately and sets errno to ECHILD, indicating that no 
child processes exist for the calling process. 
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cwait, exit, exit 


/* WAIT.C: This program launches several child processes and waits for 
* the first to finish. 


i 


#tdefine INCL_NOPM 

#tdefine INCL_NOCOMMON 

#tdefine INCL_DOSPROCESS 

#Finclude <os2.h> /* DosSleep = */ 
#Finclude <process.h> /* wait */ 
#include <stdlib.h> 

#include <stdio.h> 

#Hinclude <time.h> 
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/* Macro to get a random integer within a specified range */ 
#tdefine getrandom( min, max ) ((rand() % (int)(((max) + 1) - (min))) + (min)) 


struct CHILD 
{ 
int pid; 
char name(10]; 
} child[4] = { { @, "Ann™ }, ( @, "Beth" }, (8, "Carl" }, { O, "Dave" } }; 


void main( int argc, char *argv[] ) 
( 
int termstat, pid, c, tmp; 


srand( (unsigned)time( NULL ) ); /* Seed randomizer */ 
/* If no arguments, this is the parent. */ 

if( argc == 1 ) 

{ 


/* Spawn children in random order with a random delay. */ 
tmp = getrandom( 0, 3 ); 
for( c = tmp; c < tmp + 4; c++ ) 
child[c % 4].pid = spawnl( P_NOWAIT, argv(@], argv(@], 
child{e % 4].name, NULL ); 


/* Wait for the first children. Only get ID of first. */ 
printf( “Who's first?2?\n" ); 
pid = wait( &termstat ); 
for( c= @;3; c < 33 ctt ) 
wait( &termstat ); 


/* Check IDs to see who was first. */ 
for( c = @; c < 4; c++ ) 
if( pid == child€c].pid ) 
printf( "%s was first\n\n", child{[c].name ); 
} 


/* If there are arguments, this must be a child. */ | 
else 
{ | 
/* Delay for random time. */ 
srand( (unsigned)time( NULL ) * argv{1](@] ); 
DosSleep( getrandom( 1, 5) * 1@@@L ); 
printf( “Hi, dad. It's %s.\n", argv{1] ); 
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Output 


Who's first? 

Hi, dad. It's Carl. 
Hi, dad. It's Ann. 
Hi, dad. It's Beth. 
Hi, dad. It's Dave. 
Carl was first 
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Description Controls word wrap. 
#include <graph.h> 
short far _wrapon( short option ); 
option Wrap condition 


Remarks The _wrapon function controls whether text output with the _outtext function wraps to a 
new line or is simply clipped when the text output reaches the edge of the defined text win- 
dow. The option argument can be one of the following manifest constants: 


Constant Meaning 
_GWRAPOFF Truncates lines at window border 
_GWRAPON Wraps lines at window border 
Note that this function does not affect the output of presentation-graphics routines or font 
routines. 
Return Value The function returns the previous value of option. There is no error return. 


Compatibility O ANS! @ DOS M OS?2 QO UNIX O XENIX 


SeeAlso _outtext, _settextwindow 


Example 


/* WRAPON.C */ 


dHinclude <conio.h> 
#Hinclude <graph.h> 


void main() 
{ 
_wrapon( _GWRAPON ); 
while( !kbhit() ) 
"  _outtext( "Wrap on! ~ 0% 
getch(); 
_Outtext( "\n\n" ); 


_wrapon( _GWRAPOFF ); 
while( !kbhit() ) 
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_outtext( “Wrap off! "“ ); 
getch(); 
_outtext( "\n\n" ); 
} 


Output 


Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap 
on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! 
Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wr 
ap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap o 
n! Wrap on! Wrap on! 


Wrap off! Wrap off! Wrap off! Wrap off! Wrap off! Wrap off! Wrap off! Wrap 
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Description 


Remarks 


Return Value 


Writes data to a file. 
#include <io.h> Required only for function declarations 


int write( int handle, void *buffer, unsigned int count ); 


handle Handle referring to open file 
buffer Data to be written 
count Number of bytes 


The write function writes count bytes from buffer into the file associated with handle. The 
write operation begins at the current position of the file pointer (if any) associated with the 
given file. If the file is open for appending, the operation begins at the current end of the 
file. After the write operation, the file pointer is increased by the number of bytes actually 
written. 


The write function returns the number of bytes actually written. The return value may be 
positive but less than count (for example, when write runs out of disk space before count 
bytes are written). 


A return value of —1 indicates an error. In this case, errno is set to one of the following 
values: 


Value Meaning 
EBADF Invalid file handle or file not opened for writing 
ENOSPC No space left on device 


If you are writing more than 32K (the maximum size for type int) to a file, the return value 
should be of type unsigned int. (See the example that follows.) However, the maximum 
number of bytes that can be written to a file at one time is 65,534, since 65,535 (or 
OxFFFF) is indistinguishable from —1 and would return an error. 


If the file is opened in text mode, each line-feed character is replaced with a carriage- 
return-line-feed pair in the output. The replacement does not affect the return value. 


When writing to files opened in text mode, the write function treats a CTRL+Z character as 
the logical end-of-file. When writing to a device, write treats a CTRL+Z character in the 
buffer as an output terminator. 
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Compatibility O ANS! @ DOS @ OS/2 WM UNIX Wf XENIX 


See Also fwrite, open, read 


Example 


/* WRITE.C: This program opens a file for output and uses write to 
* write some bytes to the file. 
x] 


dFinclude <io.h> 
d#Hinclude <stdio.h> 
dHinclude <stdlib.h> 
#Finclude <fcntl.h> 
fHinclude <sys\types.h> 
_ dHinclude <sys\stat.h> 


char buffer[] = "This is a test of ‘write’ function"; 


void main() 
{ 
int fh; 
unsigned byteswritten; 


if( (fh = open( "write.o", O_RDWR | O_CREAT, S_IREAD | S_IWRITE )) != -1 ) 
{ 
if( (byteswritten = write( fh, buffer, sizeof( buffer ) )) == -1 ) 
perror( "Write failed" ); 
else 
printf( "Wrote Zu bytes to file\n", byteswritten ); 


close( fh ); 


Output 


Wrote 35 bytes to file 


Index 
A 


abort, 51, 76 
abs, 78 
Absolute value 
abs, 78 
cabs, 134 
cabsl, 134 
fabs, 263 
fabsl, 263 
labs, 441 
access, 24, 80 
‘Access mode, 269, 295, 315, 326 
acos, 46, 82 
acosl, 46, 82 
alloca, 48, 84 
Allocation. See Memory allocation 
_amblksiz variable, 63 
Appending 
constants, 523, 704 
streams, 295, 315, 326 
_arc, _arc_w, _arc_wxy 
description, 86 
use, 30 
Arccosine function, 82 
Arcsine function, 90 
Arctangent function, 94 
Arguments 
singularity, 480 
type checking, vi 
variable-length number, 62, 817 
asctime, 60, 88 
asin, 46, 90 
asinl, 46, 90 
assert, 92 
Assertions, 92 
atan, atan2, 46, 94 
atanl, atan21, 46, 94 
atexit, 51, 96 
atof, atoi, atol, _atold, 22, 98 
Attributes, 29 


B 


_bealloc, 136 

bdos, 57, 101 

_beginthread, 103 

Bessel functions 
described, 48, 107 


jO,jl jn, 107 
~ _j01,_jll,_jnl, 107 
y0,y1,yn, 107 
_y0l,_yll,_ynl, 107 
_bexpand, 260 
_bfree, 310 
_bfreeseg, 110 
_bheapadd, 406 
_bheapchk, 409 
_bheapmin, 411 
_bheapseg, 112 
_bheapset, 412 
_bheapwalk, 415 
Binary 
format, conversion to IEEE 
double precision, 181 
int 
reading, 389 
writing, 597 
mode 
_fmode, 66 
fdopen, 269 
fopen, 296 
freopen, 315-316 
_fsopen, 327 
open, 523 
setmode, 664 
sopen, 704 
vs. text mode, 35 
search, 132, 447, 466 
BINMODE.OBJ, 66 
_bios_disk, 57, 115 
_bios_equiplist, 57, 119 
_bios_keybrd, 57, 121 
_bios_memsize, 57, 124 
_bios_printer, 57, 125 
_bios_serialcom, 57, 127 
_bios_timeofday, 57, 130 
_bmalloc, 476 
_bmsize, 519 
Bold type, use of, ix 
Brackets, double, use of, ix 
_brealloc, 607 
bsearch, 55, 132 
Buffer manipulation 
_fmemccpy, 487 
_fmemchr, 489 
_fmemcmp, 491 
_fmemepy, 494 
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Buffer manipulation (continued) isspace, 21, 434 
_fmemicmp, 497 isupper, 21 
_fmemmove, 501 isxdigit, 21, 434 
_fmemset, 504 toascii, 21, 796 
memccpy, 487 tolower, _tolower, 21, 796 
memchr, 489 toupper, _toupper, 21, 796 
memcmp, 491 Characters 
memcpy, 494 converting. See Character classification and 
memicmp, 497 conversion functions 
memmove, 501 device, 437 
memset, 504 reading 
Buffering fgetc, fgetchar, 278 
described, 37 from console, 348 
preopened streams, 40 from port, 425. 
using, 40 getc, getchar, 346 
Buffers read function, 605 
assigning, 648 ungetting, 805, 807 
comparing, 491, 497 writing 
copying, 487, 494 fputc, fputchar, 305 
flushing, 276, 292 putc, putchar, 589 
searching, 489 to console, 591 
setting characters, 504 to port, 532 
BUFSIZ constant, 37 write function, 826 
Byte order, swapping, 783 chdir, 23, 145 
_chdrive, 147 
C Child process 
cwait 
cabs, 46, 134 signal settings, 707 
cabsl, 46, 134 termination-status word, 177, 707, 820 
calloc, 48, 136 exec, 251 
Carry flag floating-point state of parent, 300 
bdos, 101 spawn, 707 
int86, 426 wait, 820 
int86x, 428 chmod, 24, 149 
intdos, 430 chsize, 24, 151 
intdosx, 432 _clear87, 46, 153 
Case in file names, 9 clearerr, 37, 155 
ceil, 46, 138 _clearscreen, 29, 157 
Ceiling function, 138 Clipping regions, 650 
ceill, 46, 138 clock, 60, 159 
_cexit, _c_exit, 140 clock_t type, 68 
cgets, 44, 141 close, 42, 161 
_chain_intr, 57, 60, 143 Comparison 
Character classification and conversion functions max macro, 484 
include files, 22 min macro, 506 
isalnum, 21, 434 Compatibility mode, 704 
iscntrl, 434 complex type, 68 
isdigit, 434 CONIO.H, 44 
isgraph, 434 Console, ungetting characters from, 807 
islower, 21, 434 _control87, 46, 163 


isprint, 21, 434 
ispunct, 21, 434 
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Conversion 


characters. See Character classification and conversion 


functions 
data. See Data conversion 
floating-point numbers 


IEEE double to MS binary double, 181 
to integers and fractions, 513 


to strings, 243, 267, 340 
integers to strings, 438 


long integers to strings, 471, 801 


strings to 
floating-point values, 98 
lowercase, 750 
uppercase, 780 
time. See Time, conversion 
cos, cosh, 46, 166 
Cosine, 166 
cosl, coshl, 46 
cprintf, 8, 44, 168 
cputs, 44, 170 
creat, 42, 171 
escanf, 8, 44, 173 
ctime, 60, 175 
CTYPE.H routines, 22, 434 
cwait, 177 


D 


Data conversion 
See also Conversion 
atof, atoi, atol, _atold, 22, 98 
ecvt, 22, 243 
fevt, 22, 267 
gcvt, 22, 340 
include files, 22 
itoa, 22, 438 
Itoa, 22, 471 
strtod, strtol, strtoul, 22, 775 
ultoa, 23, 801 
Data items 
reading, 308 
writing, 338 
Date routines. See Time, routines 
Daylight variable, 64, 799 
Default translation mode 
child process, used in, 707 
_fmode, 66 
_fopen, 296 
_fsopen, 327 
O_TEXT, 523 
setmode, 664 
sopen, 704 


dieeetomsbin, dmsbintoiece, 46, 181 
difftime, 61, 182 
DIRECT.H, 23 
Directories 
creating, 507 
deleting, 624 
getting current, 354, 356 
renaming, 620 
Directory control 
chdir, 23 
chmod, 149 
getcwd, 23, 354 
_getdcwd, 356 
include files, 23 
mkdir, 23, 507 
remove, 619 
rmdir, 23 
unlink, 809 
_disable, 57, 60, 184 
diskfree_t structure, 69 
diskinfo_t structure, 69 
_displaycursor, 185 
div, 187 
div_t type, 69 
Division 
div, 187 
Idiv, 445 
Document conventions, ix 
DOMAIN, 480 
DOS commands, execution within programs, 784 
DOS error codes, 65 
DOS interface routines 
bdos, 57, 101 
_bios_disk, 115 
_bios_equiplist, 119 
_bios_keybrd, 121 
_bios_memsize, 124 
_bios_printer, 125 
_bios_timeofday, 130 
_chain_intr, 143 
_disable, 184 
_dos_allocmem, 189 
_dos_close, 191 
_dos_creat, dos_creatnew, 193 
_dos_findnext, 195 
. _dos_freemem, 198 
_dos_getdate, 200 
_dos_getdiskfree, 202 
_dos_getdrive, 204 
_dos_getfileattr, 206 
_dos_getftime, 208 
_dos_gettime, 211 
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DOS interface routines (continued) 
_dos_getvect, 213 
_dos_keep, 214 
_dos_open, 216 
_dos_read, 219 
_dos_setblock, 221 
_dos_setdate, 223 
_dos_setdrive, 225 
_dos_setfileattr, 227 
_dos_setftime, 229 
_dos_settime, 232 
_dos_setvect, 234 
_dos_write, 237 
dosexterr, 239 
_enable, 59, 247 
FP_OFF, 59 
harderr, _hardresume, _hardretn, 59 
include files, 57 
int86, 59, 426 
int86x, 428 
intdos, 59, 430 
intdosx, 432 
segread, 59, 640 
and uses (list), 57 

DOS interrupts, invoking, 426, 428 

DOS system calls 
_bios_serialcom, 127 
error handling, 239 
invoking, 101, 430, 432 

DOS version number, detection, 67 

DOS.H, 57 

_dos_allocmem, 57, 189 

_dos_close, 57, 191 

_dos_creat, 57, 193 

_dos_creatnew, 58, 193 

dosdate_t structure, dostime_t structure, 69 

_dosermovariable, 65 

DOSERROR type, 69, 239 

dosexterr, 59, 239 

_dos_findfirst, 58, 195 

_dos_findnext, 58, 195 

_dos_freemem, 58, 198 

_dos_ getdate, 58, 200 

_dos_getdiskfree, 58, 202 

_dos_getdrive, 58, 204 

_dos_getfileattr, 58, 206 

_dos_getftime, 58, 208 

_dos_gettime, 58, 211 

_dos_getvect, 58, 213 

_dos_keep, 58, 214 

_dos_open, 58, 216 

_dos_read, 58, 219 


_dos_setblock, 58, 221 
_dos_setdate, 58, 223 


' _dos_setdrive, 58, 225 


_dos_setfileattr, 58, 227 
_dos_setftime, 58, 229 
_dos_settime, 59, 232 
_dos_setvect, 59, 234 
_dos_write, 59, 237 
Drive routines 
_chdrive, 147 
_getdrive, 359 
dup, dup2, 42, 241 
Dynamic allocation. See Memory allocation 


E 


E2BIG, 66 
EACCES, 66 
EBADF, 66, 826 
ecvt, 22, 243 
EDEADLOCK, 66 
EDOM, 66 
EEXIST, 66 
EINVAL, 66 
_ellipse, _ellipse_w,_ellipse_wxy, 30, 245 
Ellipses, x 
EMFILE, 66 
_enable, 59, 247 
End-of-file 
indicators, 155 
low-level I/O, 249 
stream I/O 
clearing, 155, 622 
described, 272 
_endthread, 248 
ENOENT, 66 
ENOEXEC, 66 
ENOMEM, 66 
ENOSPC, 66, 826 
environ variable, 67-68, 360, 592 
Environment variables 
described, 68 
getenv, 360 
putenv, 592 
eof, 42, 249 
EOF constant, 37 
ERANGE, 66 
ermo variable 
and perror, strerror, 13 
described, 65 
error numbers, 538, 742 
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ermo variable (continued) 
graphics, routines, 13 
I/O routines, 13, 43 
math routines, 13 
Error handling 
DOS error codes, 65 
DOS system calls, 239 
logic errors, 92 
perror, 13, 538 
strerror, _strerror, 13, 742 
Error indicator 
described, 41, 155 
ferror, 274 
return value, 13 
Error messages, user supplied, 538, 742 
Euclidean distance, 421 
exception type, 69, 480 
EXDEYV, 66 
exec family, 8, 52, 251 
exit, exit, 52, 256 
Exiting processes, 256 
exp, 46, 258 
_expand, 48, 260 
expl, 46, 258 
Exponential functions 
exp, 258 
expl, 258 
frexp, 318 
frexpl, 318 
Idexp, 443 
Idexpl, 443 
log, log10, 459 
log], log101, 459 
pow, 578 
powl, 578 
sqrt, 717 
sqrtl, 717 


F 


' fabs, 46, 263 
fabsl, 46, 263 
Far pointers, 298 
_fealloc, 136 
fclose, fcloseall, 37, 265 
fevt, 22, 267 
fdopen, 37, 269 
feof, 37, 272 
ferror, 37, 274 
_fexpand, 260 
fflush, 37, 276 
_ffree, 48, 310 


fgetc, fgetchar, 37, 278 
fgetpos, 37, 280 
fgets, 37, 282 


_fheapchk, 48, 409 
_fheapmin, 411 
_fheapset, 49, 412 
_fheapwalk, 49, 415 


fieeetomsbin, fmsbintoieee, 47 
FILE 
pointer, 37 
structure, 37 
type, 69 
File handles 
duplication, 241 
functions, 42 
predefined, 43 
stream, 287 
File handling 
access, 24, 80 
chmod, 24 
chsize, 24, 151 
filelength, 24, 285 
fstat, 24, 329 
include files, 23 
isatty, 23, 437 
locking, 23, 456 
mktemp, 23, 509 
remove, 23 
rename, 24, 620 
setmode, 24, 664 
stat, 24, 723 
umask, 24, 803 
unlink, 24 
File permission mask. See Permission setting 
File pointers . 
defined, 41 
positioning 
fgetpos, 280 
fseek, 322 
fsetpos, 324 
ftell, 332 
Iseek, 468 
read and write operations, 43 
rewind, 622 
tell, 788 
File status information, 329, 723 
filelength, 24, 285 
fileno, 37, 287 
Files 
changing size, 151 
closing, 43, 161 
creating, 171, 523, 704 
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Files (continued) 
deleting, 619, 809 
determining length, 285 
locking, 456 
modifying names, 509 
names, 8 
obtaining status, 329, 723 
opening 
creat, 171 
input and ouput, 42 
open, 523 
sopen, 704 
reading characters, 605 
renaming, 620 
setting modification time, 811 
writing characters, 826 
find_t structure, 69 
Floating point 
control word, 163 
errors, 300 
math package 
_clear87, 153 
_ _control87, 163 
_fpreset, 300 
reinitialization, 300 
_status87, 725 
numbers, conversion to strings, 243, 267, 340 
routines, 15 
status word, 153, 725 
_floodfill,_ floodfill_w, 30, 288 
floor, 47, 290 
floorl, 47, 290 
flushall, 37, 292 
Flushing buffers, 276, 292 
_fmalloc, 49, 476 
_fmemccpy, 20, 487 
_fmemchr, 20, 489 
_fmemcmp, 491 
_fmemcpy, 20, 494 
_fmemicmp, 20, 497 
_fmemmove, 20, 501 
_fmemset, 20, 504 
fmod, 47, 293 
_fmode variable, 66 
fmodl, 47, 293 
_fmsize, 49, 519 
Fonts 
bit-mapped, 656 
functions (list), 32 
fopen, 37, 295 


Formatted I/O 

cprintf, 168 

cscanf, 173 

fprintf, 303 

fscanf, 320 

printf, 580 

scanf, 630 

sprintf, 715 

sscanf, 720 

vfprintf, vprintf, vsprintf, 817 
FP_OFF, FP_SEG, 59, 298 
fpos_t type, 69 
_fpreset, 47, 300 
fprintf, 8, 38, 303 
fputc, fputchar, 38, 305 
fputs, 38, 307 
fread, 38, 308 
_frealloc, 607 
free, 48, 310 
_freect, 48, 313 
freopen, 38, 315 
frexp, 47, 318 
frexpl, 47, 318 
fscanf, 8, 38, 320 


- fseek, 38, 322 


fsetpos, 38, 324 
_fsopen, 38, 326 
fstat, 24, 329 
_fstrcat, 727 
_fstrchr, 729 
_fstremp, 731 
_fstrepy, 734 
_fstrespn, 736 
_fstrdup, 740 
_fstricmp, 746 
_fstrlen, 748 
_fstrlwr, 750 
_fstrncat, 752 
_fstrncmp, 754 
_fstrncpy, 756 
_fstrnicmp, 758 
_fstrnset, 759 
_fstrpbrk, 761 
_fstrrchr, 763 
_fstrrev, 765 
_fstrset, 767 
_fstrspn, 769 
_fstrstr, 771 
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_fstrtok, 778 

_fstrupr, 780 

ftell, 38, 332 

ftime, 61, 334 

_fullpath, 336 

Functions 
declarations, 7—9 
vs. macros, 10-12 

fwrite, 38, 338 


G 


gevt, 22, 340 
_getactivepage, 342 
_getarcinfo, 344 
_getbkcolor, 29, 345 
getc, getchar, 38, 346 
getch, getche, 44, 348 
_getcolor, 29, 350 
_getcurrentposition, _getcurrentposition_w, 30, 352 
getcwd, 23, 354 
_getdcwd, 356 
_getdrive, 359 
getenv, 360 
_getfillmask, 29, 362 
_getfontinfo, 364 
_getgtextextent, 365 
_getgtextvector, 366 
_getimage, _getimage_w, _getimage_wxy, 32, 367 
_getlinestyle, 29, 370 
_getphyscoord, 27, 372 
* getpid, 52, 373 
_getpixel, _getpixel_w, 30, 374 
gets, 38, 376 
_gettextcolor, 31,377 
_gettextcursor, 378 
_gettextposition, 31, 379 
_gettextwindow, 381 
_getvideoconfig, 27, 382 
_getviewcoord, _getviewcoord_w, 
_getviewcoord_wxy, 27, 386 
_getvisualpage, 388 
getw, 38, 389 
_getwindowcoord, 26, 391 
_getwritemode, 392 
Global variables 
accessing, 63 
_amblksiz, 63 
daylight, 64,799 — 
_dosermo, 65 
environ, 67, 360, 592 


Global variables (continued) 


ermo 
' described, 65 
perror, 538 
strerror, 742 
_fmode, 66 
_osmajor, 67 
_osminor, 67 
_psp, 68 
sys_errlist 
described, 65 
perror, 538 
strerror, 742 
sys_nerr, 65, 538, 742 
timezone, 64, 799 
tzname, 64, 799 


gmtime, 61, 394 
Goto, nonlocal, 463, 660 
Graphics 


attributes, 29 
color selection, 29, 647 
configuration, 26, 680, 690 
coordinates, 26, 650, 686, 688 
font functions (list), 32 
image transfer, 31 
low-level palettes, 28 
output, 245, 449, 517, 610 
parameters, 652, 654, 661 
presentation graphics, 33—34, 540, 544, 546, 550 
text output, 30 
text support 
_gettextwindow, 381 
_scrolltextwindow, 635 
_settextrows, 675 
_settextwindow, 677 
_setvideomoderows, 684 | 
_setwindow, 691 
_wrapon, 824 


Greenwich mean time, 394 
_grstatus, 396 


halloc, 48, 400 

Handle. See File handles 
_harderr, 59 

_hardresume, 59 

_hardretn, 59 

Header files. See Include files 
Heap consistency check 


_bheapchk, 409 
_bheapmin, 411 
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Heap consistency check (continued) 
_fheapchk, _heapchk, _nheapchk, 409 
_fheapmin, _heapmin, _nheapmin, 411 

_heapadd, 406 

_heapchk, 409 

_heapmin, 411 

_heapset, 412 

_heapwalk, 415 

hfree, 49, 419 

_huge data items, 16-17 

Hyperbolic 
cosine, 166 
sine, 702 
tangent, 786 

hypot, 47, 421 

Hypotenuse, 421 

hypotl, 47, 421 


/ 


IEEE format, converting double-precision to Microsoft 
binary, 181 
_imagesize, _imagesize_w, _imagesize_wxy, 32, 423 
#include directive, 6 
Include files 
buffer manipulation routines, 20 
character classification, conversion, 22 
console and port I/O, 44 
Contents,5,7 
data conversion, 22 
directory control, 23 
DOS interface routines, 57 
file handling, 23 
low-level I/O, 42 
math routines, 46 
memory allocation, 48 
naming conventions, vi 
process control, 51 
processor calls, 61 
reasons for using, 6 
searching and sorting, 55 
stream I/O, 36 
string manipulation, 55 
time routines, 61 
inp, inpw, 44-45, 425 
int86, 59, 426 
int86x, 59, 428 
intdos, 59, 430 
intdosx, 59, 432 
Integers 
conversion to strings, 438 
long, conversion to strings, 471, 801 


Interrupt signals, 696 
Interrupts. See DOS interrupts, invoking 
1/O 
See also Formatted I/O 
buffered, 37 
console and port 
cgets, 44, 141 
cprintf, 44, 168 
cputs, 170 
cscanf, 44, 173 
described, 35 
getch, getche, 44, 348 
include files, 44 
inp, inpw, 44, 425 
kbhit, 44, 440 
outp, outpw, 44, 532 
putch, 44, 591 
ungetch, 44, 807 
low-level 
close, 42, 161 
creat, 42, 171 
described, 35 
dup, dup2, 42, 241 
eof, 42, 249 
error handling, 43 
include files, 42 
Iseek, 42, 468 
open, 42, 523 
read, 42, 605 
sopen, 42, 704 
tell, 42, 788 
_ write, 42, 826 
_ Stream, 35-36 
IO.H, 23, 42 
isalnum, isdigit, isgraph, 21, 434 
isalpha, isascii, iscntrl, 434 
isatty, 24, 437 
isdigit, 434 
islower, isupper, isxdigit, 21, 434 
isprint, 21, 434 
ispunct, 21, 434 
isspace, 21, 434 
Italic letters, use of, ix 
itoa, 22, 438 


J 


jO, jl, jn, 107 
_jOl, _jll, _jn!, 107 
jmp_buf type, 69 


Index 837 


K 


kbhit, 44, 440 
Keystroke, testing, 440 


L 


labs, 441 
Idexpl, 47, 443 
Idiv, 445 
Idiv_t type, 69 
Ifind, 55, 447 
Library (.LIB) files 
contents, 5 
default, 6 
GRAPHICS.LIB, 6 
use, 6 
Library routines, calling, 5 
Lines 
reading, 282, 376 
writing, 596 
_lineto, 30, 449 
_lineto_w, 30, 449 
Local time corrections, 64, 454, 799 
localeconv, 451 
Localization 
localeconv, 451 
setlocale, 662 
localtime, 61, 454 
locking, 24, 456 
log, log10, 459 
Logarithmic functions, 47, 459 
logl, log10l, 459 
long double functions, 461 
Long integers, conversion to strings, 471 
longjmp, 463 
Low-level graphics 
See also individual function names 
color selection, 28-29 
configuration, 26 
coordinates, 26 
font functions. See Fonts 
image transfer, 31 
output 
_arc, _arc_w, _arc_wxy, 30, 86 
_ellipse, _ellipse_w, _ellipse_wxy, 30, 245 
_getarcinfo, 344 
_getwritemode, 392 
_fprstatus, 396 
_lineto, _lineto_w, 30, 449 
_pie, _pie_w, _pie_wxy, 30, 567 
_polygon, _polygon_w, _polygon_wxy, 574 


Low-level graphics (continued) 
output (continued) 
_rectangle, _rectangle_w, _rectangle_wxy, 
30, 610 
_setwritemode, 695 
palettes, 28 
parameters, 30 
physical coordinates, 26 
text support (list), 30 
view coordinates, 26 
window coordinates, 26 
_lrotl, 465 
_lrotr, 465 
Isearch, 55, 466 
Iseek, 42, 468 
Itoa, 22, 471 


M 


_makepath, 473 
Macros, 10-12 
malloc, 49, 476 
MALLOC.H, 48 
Mask. See Permission setting 
MATH.H, 22, 46 
matherr 
described, 480 
use, 47 
_matherrl, 480 
max, 484 
_memavl, 49, 485 
memccpy, 20, 487 
memchr, 20, 489 
memcmp, 20, 491 
memcpy, 20, 494 
memicmp, 20, 497 
_memmax, 49, 499 
memmove, 20, 501 
Memory allocation 
_amblksiz, 63 
available memory, determination, 313 
_bealloc, 136 
_bfree, 310 
_bfreeseg, 110 
_bheapadd, 406 
_bheapchk, 409 
_bheapmin, 411 
_bheapseg, 112 
_bheapset, 412 
_bheapwalk, 415 
_bmalloc, 476 
_bmsize, 519 
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Memory allocation (continued) 
_brealloc, 607 
calloc, 136 
_expand, 260 
_fealloc, 136 
_ffree, 310 
_fheapchk, 409 
_theapmin, 411 
_fheapset, 412 
_fheapwalk, 415 
_fmalloc, 476 
_fmsize, 519 
_frealloc, 607 
free, 310 
_freect, 313 
halloc, 400 
_heapadd, 406 
_heapchk, 409 
_heapmin, 411 
_heapset, 412 
_heapwalk, 415 
hfree, 419 
malloc, 476 
_memavl, 485 
_memmax, 499 
_Insize, 519 
_ncalloc, 136 
_nfree, 310 
_nheapchk, 409 
_nhheapmin, 411 
_nheapset, 412 
_nheapwalk, 415 
_nmalloc, 476 
_nmsize, 519 
_nrealloc, 607 
realloc, 607 
routines and uses (list), 48 
stackavail, 722 

MEMORY.H, 20 

memset, 20, 504 

Microsoft Windows, 25 

min, 506 

mkdir, 23, 507 

mktemp, 24, 509 

mktime, 61, 511 

Model-independent memory routines, 20 

modf, 47, 513 

modfl, 47, 513 

Modification time, 811 

Monofont, use of, x 

movedata, 515 

_moveto, 30, 517 


_moveto_w, 30,517 
MS C 4.0, differences, puts, 596 
_msize, 49, 519 


N 


_ncalloc, 136 
NDEBUG, 92 
_hexpand, 260 
_nfree, 48, 310 
_nheapchk, 48, 409 
_nheapmin, 411 
_nheapset, 49, 412 
_nheapwalk, 49, 415 
_nmalloc, 49, 476 
_nmsize, 49, 519 
Nonlocal goto, 463, 660 
_nrealloc, 607 
_nstrdup, 740 

Null pointer, 37 


0 


Object (.OBJ) files, 6 
O_BINARY, 66 

oflag. See Open flag 
onexit, 52,521 

open, 8, 42, 523 

Open flag, 523, 704 
Operating system, 14 
Optional items, ix 
_Osmajor variable, 67 
_osminor variable, 67 
_outgtext, 32, 527 
_outmem, 530 

outp, outpw, 44-45, 532 
Output. See I/O 
_outtext, 31,535 
OVERFLOW, 480 
Overlapping moves, 494 
Overlay, of parent process, 707 


P 


Palettes, low-level, 28 


Parameters, variable-length number, 62, 817 


Parent process 
cwait, 177 
described, 251 
overlay and suspension, 707 
wait, 820 
Path names, 9 
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_pclose, 537 
Permission setting 

access, 80 

changing, 149 

described, 171 

mask, 803 

open, 523 

sopen, 704 

umask, 803 
perror, 13, 538 
_pg_analyzechart, 34, 540 
_pg_analyzechartms, 34, 540 
_pg_analyzepie, 34, 543 
_pg_analyzescatter, 34, 544 
_pg_analyzescatterms, 34, 544 
_pg_chart, 33, 546 
_pg_chartms, 33, 546 
_pg_chartpie, 33, 549 
_pg_chartscatter, 33, 550 
_pg_chartscatterms, 33, 550 
_pg_defaultchart, 33, 552 
_pg_getchardef, 34, 554 
_pg_getpalette, 34, 555 
_pg_getstyleset, 34, 558 
_pg_hlabelchart, 34, 559 
_pg_initchart, 33, 560 
_pg_resetpalette, 34, 561 
_pg_resetstyleset, 34, 562 
_pg_setchardef, 34, 563 
_pg_setpalette, 34, 564 
_pg_setstyleset, 34, 565 
_pg_vlabelchart, 34, 566 
_pie, _pie_w, _pie_wxy, 30, 567 
_pipe, 570 
Pipes 

_pclose, 537 

_pipe, 570 

_popen, 576 
PLOSS, 480 
Pointers, long, 298 
_polygon, _polygon_w, _polygon_wxy, 574 
_popen, 576 
Port I/O. See I/O, console and port 
pow, 47, 578 
Predefined 

handles, 43 

stream pointers, 39 

types. See Standard types 
printf, 38, 580 
Printing. See Write operations 


Process control 

abort, 51, 76 

atexit, 51, 96 

_cexit, _c_exit, 140 

cwait, 177 

exec family, 52 

exit, exit, 52, 256 

getpid, 52, 373 

include files, 51 

onexit, 52, 521 

raise, 52, 601 

signal, 52, 696 

spawn family, 53 

system, 53, 784 

wait, 820 
Process ID, 373 
PROCESS.H, 51 
Processor calls, include files, 61 
Program segment prefix (PSP), 68 
Pseudorandom integers, 603, 718 
_psp, 68 
pute, putchar, 38, 589 
putch, 44, 591 
putenv, 592 
_putimage, _putimage_w, 32, 594 
puts, 38 - 
putw, 38, 597 


Q 


qsort, 55, 599 


- Quick sort algorithm, 599 


Quotation marks, use of, x 


R 


raise, 52, 601 
rand, 603 
Random access 
fgetpos, 280 
fseek, 322 
fsetpos, 324 
ftell, 332 
Iseek, 468 
rewind, 622 
tell, 788 
Random number generator, 603, 718 
read, 42, 605 
Read access. See Permission setting 
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Read operations 
binary int value, 389 
characters 
from file, 605 
from stdin, 278, 346 
from stream, 278, 346 
from console, 141, 173, 348, 440 
formatted 
escanf, 173 
fscanf, 320 
scanf, 630 
sscanf, 720 
line 
from stdin, 376 
from stream, 282 
from port, 425 
realloc, 49, 607 
Reallocation 
_brealloc, 607 
_expand, 260 
_frealloc, 607 
_nrealloc, 607 
realloc, 49, 607 
_rectangle, _rectangle_w, _rectangle_wxy, 30, 610 
Redirection, 40, 43-44, 315 
_registerfonts, 32, 612 
REGS type, 70 
Remainder function, 293 
_remapallpalette, 28, 613 
_remappalette, 28, 613 
remove, 24, 619 
rename, 24, 620 
Reversing strings, 765 
rewind, 38, 622 
rmdir, 23, 624 
rmtmp, 38, 626 
_totl, 628 
_rotr, 628 


S 


scanf, 8, 38, 630 
Scanning. See Read operations 
_scrolltextwindow, 635 
SEARCH.H, 55 
_searchenv, 638 
Searching and sorting 

bsearch, 55, 132 

include files, 55 

Ifind, 447 

Ifind, lsearch, 55 


Searching and sorting (continued) 
Isearch, 466 
qsort, 55, 599 
seed, 718 
Segment registers, 640 
segread, 59, 640 
_selectpalette, 28, 642 
_setactivepage, 26, 645 
_setbkcolor, 29, 647 
setbuf, 38, 40, 648 
_setcliprgn, 650 
_setcolor, 29, 652 
_setfillmask, 29, 654 
_setfont, 32, 656 
_setgtextvector, 659 
setjmp, 660 
_setlinestyle, 29, 661 
setlocale, 662 
setmode, 24, 664 
_setpixel, _setpixel_w, 29, 666 
_settextcolor, 31, 668 
_settextcursor, 671 
_settextposition, 673 
_settextrows, 675 
_settextwindow, 31, 677 
setvbuf, 38, 40 
_setvideomode, 26, 680 
_setvideomoderows, 684 
_setvieworg, 27, 686 
_setviewport, 27, 688 
_setvisualpage, 26, 690 
_setwindow, 27, 691 
_setwritemode, 695 
signal 
described, 53, 696 
raise, 601 
SIGNAL.H, 51 
sin, sinh, 47, 702 
Sine, 702 
SING, 480 
sinl, sinhl, 47, 702 
size_t type, 70 
Small capital letters, use of, x 
sopen, 8, 42, 704 
Sorting. See Searching and sorting 
spawn family 
argument-type-checking limitations, 8, 707 
described, 707 
use, 53 
_splitpath, 713 
sprintf, 8, 715 
sqrt, 47, 717 
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sqrtl, 47, 717 
Square-root function, 717 
srand, 718 
SREGS type, 70 
sscanf 
described, 720 
type checking, 8 
use, 38 
Stack checking, 12 
Stack environment 
restoring, 463 
saving, 660 
stackavail, 49, 722 
Standard auxiliary. See stdaux, stderr, stdin 
Standard error. See stdaux, stderr, stdin 
Standard input. See stdaux, stderr, stdin 
Standard output. See stdout, stdprn 
Standard print. See stdout, stdprn 
Standard types 
clock_t, 68 
complex, 68 
diskfree_t, 69 
diskinfo_t, 69 
div_t, 69 
dosdate_t, 69 
DOSERROR, 69, 239 
dostime_t, 69 
exception, 69, 480 
FILE, 69 
find_t, 69 
fpos_t, 69 
jmp_buf, 69 
Idiv_t, 69 
listed, 68 
REGS, 70 
size_t, 70 
SREGS, 70 
stat, 723 
time_t, 70, 182 
timeb, 70, 334 
tm, 70, 394 
utimbuf, 70, 811 
va_list, 70 
stat routine 
described, 723 
use, 24 
stat type 
described, 70 
fstat, 329 
_status87, 725 


stdaux, stderr, stdin 
buffering, 40 
described, 40 
file handle, 43 
translation mode, changing, 664 
STDIO.H, 36 
stdout, stdpm 
buffering, 40 
described, 40 
file handle, 43 
translation mode, changing, 664 
strcat, 55, 727 
strchr, 55, 729 
stremp, 55, 731 
streoll, 733 
strepy, 55, 734 
strespn, 55, 736 
_strdate, 61, 738 
strdup, 55, 740 
Stream I/O 
See also 1/O, console and port 
buffering, 40 
clearerr, 155 
described, 35 
error handling, 41 
fclose, fcloseall, 265 
fdopen, 269 
feof, 272 
ferror, 274 
fflush, 276 
fgetc, fgetchar, 278 
fgetpos, 280 
fgets, 282 
fileno, 287 
flushall, 292 
fopen, 295 
fprintf, 303 
fputc, fputchar, 305 
fputs, 307, 596 
fread, 308 
freopen, 315 
fscanf, 320 
fseek, 322 
fsetpos, 324 
_fsopen, 326 
ftell, 332 
fwrite, 338 
getc, getchar, 346 
gets, 376 
getw, 389 
printf, 580 
putc, putchar, 589 
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Stream I/O (continued) 
putw, 597 
rewind, 622 
routines and uses (list), 37 
scanf, 630 
setbuf, 648 
sprintf, 715 
sscanf, 720 
tempnam, tmpnam, 38 
ungetc, 805 
vfprintf, vprintf, vsprintf, 817 
Stream pointer, 37 
Streams 
appending, 295, 315, 326 
buffering, 648 
clearing errors, 155 
closing, 41, 265 
file handles for, 287 
file pointer position 
fseek, 322 
fsetpos, 324 
ftell, 332 
fgetpos, 280 
rewind, 622 
formatted I/O 
printf, 580 
scanf, 630 
sprintf, 715 
sscanf, 720 
stream, 303, 320 
vprintf, 817 
opening, 39, 269, 295, 326 
reading 
binary int value, 389 
characters, 278, 346 
data items, 308 
lines, 282, 376 
reopening, 315 
rewinding, 622 
stdaux, stderr, stdin, 40 
stdout, stdprn, 40 
translation mode. See Binary, mode 
ungetting characters, 805 
writing 
binary int value, 597 
characters, 305, 589 
data items, 338 
lines, 596 
strings, 307 
strerror, 13, 55, 742 


_Strerror, 742 
strftime, 744 
stricmp, 55, 746 
String manipulation 
_fstrcat, 727 
_fstrchr, 729 
_fstremp, 731 
_fstrcpy, 734 
_fstrespn, 736 
_fstrdup, 740 
_fstricmp, 746 
_fstrlwr, 750 
_fstrncat, 752 
_fstrnemp, 754 
_fstrncpy, 756 
_fstrnicmp, 758 
_fstrnset, 759 
_fstrpbrk, 761 
_fstrrchr, 763 
_fstrrev, 765 
_fstrset, 767 
_fstrspn, 769 
_fstrstr, 771 
_fstrtok, 778 
_fstrupr, 780 
_nstrdup, 740 
routines and uses (list), 55 
streat, 727 
strchr, 729 
stremp, 731 
streoll, 733, 744 
strepy, 734 
strespn, 736 
strdup, 740 
stricmp, 746 
strlwr, 750 
streat, 752 
strcmp, 754 
strncpy, 756 
strnicmp, 758 
strnset, 759 
strpbrk, 761 
strrchr, 763 
strrev, 765 
strset, 767 
strspn, 769 
strstr, 771 
strtok, 778 
strupr, 780 
strxfrm, 782 
STRING.H, 55 
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Strings 
comparing, 731, 733, 744, 746, 754, 758 
concatenating, 752 
converting 
to floating-point values, 98 
to lowercase, 750 
to uppercase, 780 
copying, 734, 740, 756 
initializing, 759, 767 
reading from console, 141 
reversing, 765 
searching 
_fstrchr, 729 
_fstrespn, 736 
_fstrpbrk, 761 
_fstrrchr, 763 
_fstrspn, 769 
_fstrstr, 771 
_fstrtok, 778 
strchr, 729 
strespn, 736 
strpbrk, 761 
strrchr, 763 
strspn, 769 
strstr, 771 
strtok, 778 
writing 
to console, 168, 170 
to stream, 307 
strlen, 56 
striwr, 56, 750 
streat, 56, 752 
stmcmp, 56, 754 
stmepy, 56, 756 
stmicmp, 56, 758 
stmset, 56, 759 
strpbrk, 56, 761 
strrchr, 56, 763 
strrev, 56, 765 
strset, 56, 767 
strspn, 56, 769 
strstr, 56, 771 
_Strtime, 61, 773 
‘strtod, 22, 775 
strtok, 56, 778 
strtol, 23,775 
_strtold, 23, 775 
strtoul, 23, 775 
strupr, 56, 780 
strxfrm, 782 
swab, 783 
SYS\STAT.H, 23 


SYS\TIMEB.H, 61 
SYS\TYPES, 61 
SYS\UTIME.H, 61 
sys_errlist 
described, 65 
system error messages, 538, 742 
sys_nerr, 65, 538, 742 
system, 53, 784 
System calls. See DOS system calls 
System time. See Time 


T 


tan, tanh, 47, 786 
Tangent, 786 
tanl, tanhl, 47, 786 
tell, 42, 788 
tempnam, tmpnam, 38, 790 
Terminal capabilities, 437 
Text mode 
vs. binary, 35 
described, 66, 523 
setmode, 664 
sopen, 704 
stream I/O, 269, 296, 315, 327 
Threads 
_beginthread, 103 
DosExit, 248 
_endthread, 248 
termination, 248 


- Time 


conversion 

long integer to string, 175 

long integer to structure, 454 

structure to string, 88 
functions, 61 
global variables, setting, 799 
local time, correcting, 454 
obtaining, 334, 793 
routines 

asctime, 88 

clock, 159 

ctime, 175 

difftime, 182 

ftime, 334 

gmtime, 394 

(list), 60 

localtime, 454 

mktime, 511 

time, 793 

tzset, 799 

utime, 811 
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Time (continued) 
time differences, computing, 182 
time function, 793 
TIME.H, 61 
time_t type, 70, 182 
timeb type, 70, 334 
timezone variable, 64, 799 
TLOSS, 480 
tm type, 70, 394 
tmpfile, 39 
tmpnam, 790 
toascii, 21, 796 
Tokens, finding in strings, 778 
_tolower, _toupper, 21, 796 
tolower, toupper, 21, 796 
_toupper, 796 
Trigonometric functions 
acos, 82 
acosl, 82 
asin, 90 
asinl, 90 
atan, atan2, 94 
atanl, atan21, 94 
cos, cosh, 166 
hypot, 421 
hypotl, 421 
sin, sinh, 702 
sinl, sinhl, 702 
tan, tanh, 786 
tanl, tanhl, 786 
Type checking 
function declarations, 7-8 
include files, 7 
variable arguments, 8 
TZ environment variable 
default value, 64 
localtime, 454 
tzset, 799 
tzname variable, 64, 799 
tzset, 799 


U 


ultoa, 23, 801 

umask, 24, 803 
UNDERFLOW, 481 

UNIX, 9 

ungetc, 39, 805 

ungetch, 44, 807 

Universal Coordinated Time, 61 
unlink, 24, 809 
_unregisterfonts, 32, 810 


Uppercase, use of, ix 
utimbuf type, 70, 811 
utime, 811 


V 


va_arg, va_end, va_start, 62 
va_list type, 70 

Version number (DOS), 67 
vfprintf, vprintf, vsprintf, 39, 817 


W 


wait, 820 
Word. See Binary, int 


_wrapon, 31, 824 


write, 42, 826 
Write access. See Permission setting 
Write operations 
binary int value to stream, 597 
character 
to console, 168 
to file, 826 
to stdout, 305, 589 
to stream, 305, 589, 805 
to console, 169, 170, 591 
data items from stream, 338 
formatted 
cprintf, 168 
printf, 580 
sprintf, 715 
stream I/O, 303 
vprintf, 817 
line to stream, 596 
to port, 532 
string to stream, 307 


X 


XENIX, 9 


Y 


yO, yl, yn, 107 
_y01, _yll, _ynl, 107 
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identifies functions by category so that you can quickly find a 
library routine even if you don’t know its name. 


The core of the book provides detailed information on each 
function in the run-time library —syntax; example programs; 
the include file, prototypes, arguments, and return values; cross- 
references to related functions; and notes on compatibility with 
ANSI, DOS, OS/2, UNIX? and XENIX* 


The MICROSOFT C RUN-TIME LIBRARY REFERENCE is 
an essential reference to the industry-standard C library. 


